

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Python API &mdash; Mod_python v3.4.1-3.4.1 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '3.4.1-3.4.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/sidebar.js"></script>
    <link rel="author" title="About these documents" href="about.html" />
    <link rel="copyright" title="Copyright" href="copyright.html" />
    <link rel="top" title="Mod_python v3.4.1-3.4.1 documentation" href="index.html" />
    <link rel="next" title="Apache Configuration Directives" href="directives.html" />
    <link rel="prev" title="Tutorial" href="tutorial.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="directives.html" title="Apache Configuration Directives"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="tutorial.html" title="Tutorial"
             accesskey="P">previous</a> |</li>
        <li><a href="contents.html">Mod_python v3.4.1-3.4.1 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="python-api">
<span id="pythonapi"></span><h1>Python API<a class="headerlink" href="#python-api" title="Permalink to this headline">¶</a></h1>
<div class="section" id="multiple-interpreters">
<span id="pyapi-interps"></span><h2>Multiple Interpreters<a class="headerlink" href="#multiple-interpreters" title="Permalink to this headline">¶</a></h2>
<p>When working with mod_python, it is important to be aware of a feature
of Python that is normally not used when using the language for
writing scripts to be run from command line. (In fact, this feature is not
available from within Python itself and can only be accessed through
the <a class="reference external" href="http://www.python.org/doc/current/api/api.html">C language API</a>.)
Python C API provides the ability to create <em class="dfn">subinterpreters</em>. A
more detailed description of a subinterpreter is given in the
documentation for the
<a class="reference external" href="http://www.python.org/doc/current/api/initialization.html">Py_NewInterpreter()</a>
function. For this discussion, it will suffice to say that each
subinterpreter has its own separate namespace, not accessible from
other subinterpreters. Subinterpreters are very useful to make sure
that separate programs running under the same Apache server do not
interfere with one another.</p>
<p id="index-0">At server start-up or mod_python initialization time, mod_python
initializes the <em>main interpeter</em>. The main interpreter contains a
dictionary of subinterpreters. Initially, this dictionary is
empty. With every request, as needed, subinterpreters are created, and
references to them are stored in this dictionary. The dictionary is
keyed on a string, also known as <em>interpreter name</em>.  This name can be
any string.  The main interpreter is named <tt class="docutils literal"><span class="pre">'main_interpreter'</span></tt>.
The way all other interpreters are named can be controlled by
<tt class="docutils literal"><span class="pre">PythonInterp*</span></tt> directives. Default behavior is to name
interpreters using the Apache virtual server name (<tt class="docutils literal"><span class="pre">ServerName</span></tt>
directive). This means that all scripts in the same virtual server
execute in the same subinterpreter, but scripts in different virtual
servers execute in different subinterpreters with completely separate
namespaces.  <a class="reference internal" href="directives.html#dir-other-ipd"><em>PythonInterpPerDirectory</em></a> and <a class="reference internal" href="directives.html#dir-other-ipdv"><em>PythonInterpPerDirective</em></a> directives
alter the naming convention to use the absolute path of the directory
being accessed, or the directory in which the <tt class="docutils literal"><span class="pre">Python*Handler</span></tt> was
encountered, respectively.  <a class="reference internal" href="directives.html#dir-other-pi"><em>PythonInterpreter</em></a> can be used to force
the interpreter name to a specific string overriding any naming
conventions.</p>
<p>Once created, a subinterpreter will be reused for subsequent requests.
It is never destroyed and exists until the Apache process ends.</p>
<p>You can find out the name of the interpreter under which you&#8217;re
running by peeking at <tt class="xref py py-attr docutils literal"><span class="pre">request.interpreter</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If any module is being used which has a C code component that uses
the simplified API for access to the Global Interpreter Lock (GIL)
for Python extension modules, then the interpreter name must be
forcibly set to be <tt class="docutils literal"><span class="pre">'main_interpreter'</span></tt>. This is necessary as such
a module will only work correctly if run within the context of the
first Python interpreter created by the process. If not forced to
run under the <tt class="docutils literal"><span class="pre">'main_interpreter'</span></tt>, a range of Python errors can
arise, each typically referring to code being run in <em>restricted
mode</em>.</p>
</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="http://www.python.org/doc/current/api/api.html">http://www.python.org/doc/current/api/api.html</a></dt>
<dd>Python C Language API</dd>
<dt><a class="reference external" href="http://www.python.org/peps/pep-0311.html">http://www.python.org/peps/pep-0311.html</a></dt>
<dd>PEP 0311 - Simplified Global Interpreter Lock Acquisition for Extensions</dd>
</dl>
</div>
</div>
<div class="section" id="overview-of-a-request-handler">
<span id="pyapi-handler"></span><h2>Overview of a Request Handler<a class="headerlink" href="#overview-of-a-request-handler" title="Permalink to this headline">¶</a></h2>
<p id="index-1">A <em class="dfn">handler</em> is a function that processes a particular phase of a
request. Apache processes requests in phases - read the request,
process headers, provide content, etc. For every phase, it will call
handlers, provided by either the Apache core or one of its modules,
such as mod_python which passes control to functions provided by the
user and written in Python. A handler written in Python is not any
different from a handler written in C, and follows these rules:</p>
<p id="index-2">A handler function will always be passed a reference to a request
object. (Throughout this manual, the request object is often referred
to by the <tt class="docutils literal"><span class="pre">req</span></tt> variable.)</p>
<p>Every handler can return:</p>
<ul>
<li><p class="first"><tt class="xref py py-const docutils literal"><span class="pre">apache.OK</span></tt>, meaning this phase of the request was handled by this
handler and no errors occurred.</p>
</li>
<li><p class="first"><tt class="xref py py-const docutils literal"><span class="pre">apache.DECLINED</span></tt>, meaning this handler has not handled this
phase of the request to completion and Apache needs to look for
another handler in subsequent modules.</p>
</li>
<li><p class="first"><tt class="xref py py-const docutils literal"><span class="pre">apache.HTTP_ERROR</span></tt>, meaning an HTTP error occurred.
<em>HTTP_ERROR</em> can be any of the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">HTTP_CONTINUE</span>                     <span class="o">=</span> <span class="mi">100</span>
<span class="n">HTTP_SWITCHING_PROTOCOLS</span>          <span class="o">=</span> <span class="mi">101</span>
<span class="n">HTTP_PROCESSING</span>                   <span class="o">=</span> <span class="mi">102</span>
<span class="n">HTTP_OK</span>                           <span class="o">=</span> <span class="mi">200</span>
<span class="n">HTTP_CREATED</span>                      <span class="o">=</span> <span class="mi">201</span>
<span class="n">HTTP_ACCEPTED</span>                     <span class="o">=</span> <span class="mi">202</span>
<span class="n">HTTP_NON_AUTHORITATIVE</span>            <span class="o">=</span> <span class="mi">203</span>
<span class="n">HTTP_NO_CONTENT</span>                   <span class="o">=</span> <span class="mi">204</span>
<span class="n">HTTP_RESET_CONTENT</span>                <span class="o">=</span> <span class="mi">205</span>
<span class="n">HTTP_PARTIAL_CONTENT</span>              <span class="o">=</span> <span class="mi">206</span>
<span class="n">HTTP_MULTI_STATUS</span>                 <span class="o">=</span> <span class="mi">207</span>
<span class="n">HTTP_MULTIPLE_CHOICES</span>             <span class="o">=</span> <span class="mi">300</span>
<span class="n">HTTP_MOVED_PERMANENTLY</span>            <span class="o">=</span> <span class="mi">301</span>
<span class="n">HTTP_MOVED_TEMPORARILY</span>            <span class="o">=</span> <span class="mi">302</span>
<span class="n">HTTP_SEE_OTHER</span>                    <span class="o">=</span> <span class="mi">303</span>
<span class="n">HTTP_NOT_MODIFIED</span>                 <span class="o">=</span> <span class="mi">304</span>
<span class="n">HTTP_USE_PROXY</span>                    <span class="o">=</span> <span class="mi">305</span>
<span class="n">HTTP_TEMPORARY_REDIRECT</span>           <span class="o">=</span> <span class="mi">307</span>
<span class="n">HTTP_BAD_REQUEST</span>                  <span class="o">=</span> <span class="mi">400</span>
<span class="n">HTTP_UNAUTHORIZED</span>                 <span class="o">=</span> <span class="mi">401</span>
<span class="n">HTTP_PAYMENT_REQUIRED</span>             <span class="o">=</span> <span class="mi">402</span>
<span class="n">HTTP_FORBIDDEN</span>                    <span class="o">=</span> <span class="mi">403</span>
<span class="n">HTTP_NOT_FOUND</span>                    <span class="o">=</span> <span class="mi">404</span>
<span class="n">HTTP_METHOD_NOT_ALLOWED</span>           <span class="o">=</span> <span class="mi">405</span>
<span class="n">HTTP_NOT_ACCEPTABLE</span>               <span class="o">=</span> <span class="mi">406</span>
<span class="n">HTTP_PROXY_AUTHENTICATION_REQUIRED</span><span class="o">=</span> <span class="mi">407</span>
<span class="n">HTTP_REQUEST_TIME_OUT</span>             <span class="o">=</span> <span class="mi">408</span>
<span class="n">HTTP_CONFLICT</span>                     <span class="o">=</span> <span class="mi">409</span>
<span class="n">HTTP_GONE</span>                         <span class="o">=</span> <span class="mi">410</span>
<span class="n">HTTP_LENGTH_REQUIRED</span>              <span class="o">=</span> <span class="mi">411</span>
<span class="n">HTTP_PRECONDITION_FAILED</span>          <span class="o">=</span> <span class="mi">412</span>
<span class="n">HTTP_REQUEST_ENTITY_TOO_LARGE</span>     <span class="o">=</span> <span class="mi">413</span>
<span class="n">HTTP_REQUEST_URI_TOO_LARGE</span>        <span class="o">=</span> <span class="mi">414</span>
<span class="n">HTTP_UNSUPPORTED_MEDIA_TYPE</span>       <span class="o">=</span> <span class="mi">415</span>
<span class="n">HTTP_RANGE_NOT_SATISFIABLE</span>        <span class="o">=</span> <span class="mi">416</span>
<span class="n">HTTP_EXPECTATION_FAILED</span>           <span class="o">=</span> <span class="mi">417</span>
<span class="n">HTTP_UNPROCESSABLE_ENTITY</span>         <span class="o">=</span> <span class="mi">422</span>
<span class="n">HTTP_LOCKED</span>                       <span class="o">=</span> <span class="mi">423</span>
<span class="n">HTTP_FAILED_DEPENDENCY</span>            <span class="o">=</span> <span class="mi">424</span>
<span class="n">HTTP_INTERNAL_SERVER_ERROR</span>        <span class="o">=</span> <span class="mi">500</span>
<span class="n">HTTP_NOT_IMPLEMENTED</span>              <span class="o">=</span> <span class="mi">501</span>
<span class="n">HTTP_BAD_GATEWAY</span>                  <span class="o">=</span> <span class="mi">502</span>
<span class="n">HTTP_SERVICE_UNAVAILABLE</span>          <span class="o">=</span> <span class="mi">503</span>
<span class="n">HTTP_GATEWAY_TIME_OUT</span>             <span class="o">=</span> <span class="mi">504</span>
<span class="n">HTTP_VERSION_NOT_SUPPORTED</span>        <span class="o">=</span> <span class="mi">505</span>
<span class="n">HTTP_VARIANT_ALSO_VARIES</span>          <span class="o">=</span> <span class="mi">506</span>
<span class="n">HTTP_INSUFFICIENT_STORAGE</span>         <span class="o">=</span> <span class="mi">507</span>
<span class="n">HTTP_NOT_EXTENDED</span>                 <span class="o">=</span> <span class="mi">510</span>
</pre></div>
</div>
</li>
</ul>
<p>As an alternative to <em>returning</em> an HTTP error code, handlers can
signal an error by <em>raising</em> the <tt class="xref py py-const docutils literal"><span class="pre">apache.SERVER_RETURN</span></tt>
exception, and providing an HTTP error code as the exception value,
e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">raise</span> <span class="n">apache</span><span class="o">.</span><span class="n">SERVER_RETURN</span><span class="p">,</span> <span class="n">apache</span><span class="o">.</span><span class="n">HTTP_FORBIDDEN</span>
</pre></div>
</div>
<p>Handlers can send content to the client using the <tt class="xref py py-meth docutils literal"><span class="pre">request.write()</span></tt>
method.</p>
<p>Client data, such as POST requests, can be read by using the
<tt class="xref py py-meth docutils literal"><span class="pre">request.read()</span></tt> function.</p>
<p>An example of a minimalistic handler might be:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>

<span class="k">def</span> <span class="nf">requesthandler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>
    <span class="n">req</span><span class="o">.</span><span class="n">content_type</span> <span class="o">=</span> <span class="s">&quot;text/plain&quot;</span>
    <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;Hello World!&quot;</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
</div>
<div class="section" id="overview-of-a-filter-handler">
<span id="pyapi-filter"></span><h2>Overview of a Filter Handler<a class="headerlink" href="#overview-of-a-filter-handler" title="Permalink to this headline">¶</a></h2>
<p id="index-3">A <em class="dfn">filter handler</em> is a function that can alter the input or the
output of the server. There are two kinds of filters - <em class="dfn">input</em> and
<em class="dfn">output</em> that apply to input from the client and output to the
client respectively.</p>
<p>At this time mod_python supports only request-level filters, meaning
that only the body of HTTP request or response can be filtered. Apache
provides support for connection-level filters, which will be supported
in the future.</p>
<p>A filter handler receives a <em>filter</em> object as its argument. The
request object is available as well via <tt class="docutils literal"><span class="pre">filter.req</span></tt>, but all
writing and reading should be done via the filter&#8217;s object read and
write methods.</p>
<p>Filters need to be closed when a read operation returns None
(indicating End-Of-Stream).</p>
<p>The return value of a filter is ignored. Filters cannot decline
processing like handlers, but the same effect can be achieved
by using the <tt class="xref py py-meth docutils literal"><span class="pre">filter.pass_on()</span></tt> method.</p>
<p>Filters must first be registered using <tt class="docutils literal"><span class="pre">PythonInputFilter</span></tt> or
<tt class="docutils literal"><span class="pre">PythonOutputFilter</span></tt>, then added using the Apache
<tt class="docutils literal"><span class="pre">Add/SetInputFilter</span></tt> or <tt class="docutils literal"><span class="pre">Add/SetOutputFilter</span></tt> directives.</p>
<p>Here is an example of how to specify an output filter, it tells the
server that all .py files should processed by CAPITALIZE filter:</p>
<div class="highlight-python"><pre>PythonOutputFilter capitalize CAPITALIZE
AddOutputFilter CAPITALIZE .py</pre>
</div>
<p>And here is what the code for the <tt class="file docutils literal"><span class="pre">capitalize.py</span></tt> might look
like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>

<span class="k">def</span> <span class="nf">outputfilter</span><span class="p">(</span><span class="nb">filter</span><span class="p">):</span>

    <span class="n">s</span> <span class="o">=</span> <span class="nb">filter</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
    <span class="k">while</span> <span class="n">s</span><span class="p">:</span>
        <span class="nb">filter</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">s</span><span class="o">.</span><span class="n">upper</span><span class="p">())</span>
        <span class="n">s</span> <span class="o">=</span> <span class="nb">filter</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>

    <span class="k">if</span> <span class="n">s</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
        <span class="nb">filter</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>When writing filters, keep in mind that a filter will be called any
time anything upstream requests an IO operation, and the filter has no
control over the amount of data passed through it and no notion of
where in the request processing it is called. For example, within a
single request, a filter may be called once or five times, and there
is no way for the filter to know beforehand that the request is over
and which of calls is last or first for this request, thought
encounter of an EOS (None returned from a read operation) is a fairly
strong indication of an end of a request.</p>
<p>Also note that filters may end up being called recursively in
subrequests. To avoid the data being altered more than once, always
make sure you are not in a subrequest by examining the <tt class="xref py py-attr docutils literal"><span class="pre">request.main</span></tt>
value.</p>
<p>For more information on filters, see <a class="reference external" href="http://httpd.apache.org/docs-2.4/developer/filters.html">http://httpd.apache.org/docs-2.4/developer/filters.html</a>.</p>
</div>
<div class="section" id="overview-of-a-connection-handler">
<span id="pyapi-conn"></span><h2>Overview of a Connection Handler<a class="headerlink" href="#overview-of-a-connection-handler" title="Permalink to this headline">¶</a></h2>
<p id="index-4">A <em class="dfn">connection handler</em> handles the connection, starting almost
immediately from the point the TCP connection to the server was
made.</p>
<p>Unlike HTTP handlers, connection handlers receive a <em>connection</em>
object as an argument.</p>
<p>Connection handlers can be used to implement protocols. Here is an
example of a simple echo server:</p>
<p>Apache configuration:</p>
<div class="highlight-python"><pre>PythonConnectionHandler echo</pre>
</div>
<p>Contents of <tt class="file docutils literal"><span class="pre">echo.py</span></tt> file:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>

<span class="k">def</span> <span class="nf">connectionhandler</span><span class="p">(</span><span class="n">conn</span><span class="p">):</span>

    <span class="k">while</span> <span class="mi">1</span><span class="p">:</span>
        <span class="n">conn</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">conn</span><span class="o">.</span><span class="n">readline</span><span class="p">())</span>

    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
</div>
<div class="section" id="module-apache">
<span id="apache-access-to-apache-internals"></span><h2><a class="reference internal" href="#module-apache" title="apache: Access to Apache Internals."><tt class="xref py py-mod docutils literal"><span class="pre">apache</span></tt></a> &#8211; Access to Apache Internals.<a class="headerlink" href="#module-apache" title="Permalink to this headline">¶</a></h2>
<p>The Python interface to Apache internals is contained in a module
appropriately named <a class="reference internal" href="#module-apache" title="apache: Access to Apache Internals."><tt class="xref py py-mod docutils literal"><span class="pre">apache</span></tt></a>, located inside the
<tt class="xref py py-mod docutils literal"><span class="pre">mod_python</span></tt> package. This module provides some important
objects that map to Apache internal structures, as well as some useful
functions, all documented below. (The request object also provides an
interface to Apache internals, it is covered in its own section of
this manual.)</p>
<p id="index-5">The <a class="reference internal" href="#module-apache" title="apache: Access to Apache Internals."><tt class="xref py py-mod docutils literal"><span class="pre">apache</span></tt></a> module can only be imported by a script running
under mod_python. This is because it depends on a built-in module
<tt class="xref py py-mod docutils literal"><span class="pre">_apache</span></tt> provided by mod_python.</p>
<p>It is best imported like this:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>
</pre></div>
</div>
<p><tt class="xref py py-mod docutils literal"><span class="pre">mod_python.apache</span></tt> module defines the following functions and
objects. For a more in-depth look at Apache internals, see the
<a class="reference external" href="http://httpd.apache.org/dev/">Apache Developer Page</a></p>
<div class="section" id="functions">
<span id="pyapi-apmeth"></span><h3>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="apache.log_error">
<tt class="descclassname">apache.</tt><tt class="descname">log_error</tt><big>(</big><em>message</em><span class="optional">[</span>, <em>level</em><span class="optional">[</span>, <em>server</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.log_error" title="Permalink to this definition">¶</a></dt>
<dd><blockquote>
<div><p>An interface to the Apache <tt class="docutils literal"><span class="pre">ap_log_error()</span></tt>
function. <em>message</em> is a string with the error message,
<em>level</em> is one of the following flags constants:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">APLOG_EMERG</span>
<span class="n">APLOG_ALERT</span>
<span class="n">APLOG_CRIT</span>
<span class="n">APLOG_ERR</span>
<span class="n">APLOG_WARNING</span>
<span class="n">APLOG_NOTICE</span>
<span class="n">APLOG_INFO</span>
<span class="n">APLOG_DEBUG</span>
<span class="n">APLOG_NOERRNO</span> <span class="o">//</span> <span class="n">DEPRECATED</span>
</pre></div>
</div>
</div></blockquote>
<p><em>server</em> is a reference to a <a class="reference internal" href="#apache.request.server" title="apache.request.server"><tt class="xref py py-meth docutils literal"><span class="pre">request.server()</span></tt></a> object. If
<em>server</em> is not specified, then the error will be logged to the
default error log, otherwise it will be written to the error log for
the appropriate virtual server. When <em>server</em> is not specified,
the setting of LogLevel does not apply, the LogLevel is dictated by
an httpd compile-time default, usually <tt class="docutils literal"><span class="pre">warn</span></tt>.</p>
<p>If you have a reference to a request object available, consider using
<a class="reference internal" href="#apache.request.log_error" title="apache.request.log_error"><tt class="xref py py-meth docutils literal"><span class="pre">request.log_error()</span></tt></a> instead, it will prepend request-specific
information such as the source IP of the request to the log entry.</p>
</dd></dl>

<dl class="function">
<dt id="apache.import_module">
<tt class="descclassname">apache.</tt><tt class="descname">import_module</tt><big>(</big><em>module_name</em><span class="optional">[</span>, <em>autoreload=1</em>, <em>log=0</em>, <em>path=None</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.import_module" title="Permalink to this definition">¶</a></dt>
<dd><p>This function can be used to import modules taking advantage of
mod_python&#8217;s internal mechanism which reloads modules automatically
if they have changed since last import.</p>
<p><em>module_name</em> is a string containing the module name (it can
contain dots, e.g. <tt class="docutils literal"><span class="pre">mypackage.mymodule</span></tt>); <em>autoreload</em> indicates
whether the module should be reloaded if it has changed since last
import; when <em>log</em> is true, a message will be written to the
logs when a module is reloaded; <em>path</em> allows restricting
modules to specific paths.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span>
<span class="n">module</span> <span class="o">=</span> <span class="n">apache</span><span class="o">.</span><span class="n">import_module</span><span class="p">(</span><span class="s">&#39;module_name&#39;</span><span class="p">,</span> <span class="n">log</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="apache.allow_methods">
<tt class="descclassname">apache.</tt><tt class="descname">allow_methods</tt><big>(</big><span class="optional">[</span><em>*args</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.allow_methods" title="Permalink to this definition">¶</a></dt>
<dd><p>A convenience function to set values in <a class="reference internal" href="#apache.request.allowed" title="apache.request.allowed"><tt class="xref py py-meth docutils literal"><span class="pre">request.allowed()</span></tt></a>.
<a class="reference internal" href="#apache.request.allowed" title="apache.request.allowed"><tt class="xref py py-meth docutils literal"><span class="pre">request.allowed()</span></tt></a> is a bitmask that is used to construct the
<tt class="docutils literal"><span class="pre">'Allow:'</span></tt> header. It should be set before returning a
<tt class="xref py py-const docutils literal"><span class="pre">HTTP_NOT_IMPLEMENTED</span></tt> error.</p>
<p>Arguments can be one or more of the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">M_GET</span>
<span class="n">M_PUT</span>
<span class="n">M_POST</span>
<span class="n">M_DELETE</span>
<span class="n">M_CONNECT</span>
<span class="n">M_OPTIONS</span>
<span class="n">M_TRACE</span>
<span class="n">M_PATCH</span>
<span class="n">M_PROPFIND</span>
<span class="n">M_PROPPATCH</span>
<span class="n">M_MKCOL</span>
<span class="n">M_COPY</span>
<span class="n">M_MOVE</span>
<span class="n">M_LOCK</span>
<span class="n">M_UNLOCK</span>
<span class="n">M_VERSION_CONTROL</span>
<span class="n">M_CHECKOUT</span>
<span class="n">M_UNCHECKOUT</span>
<span class="n">M_CHECKIN</span>
<span class="n">M_UPDATE</span>
<span class="n">M_LABEL</span>
<span class="n">M_REPORT</span>
<span class="n">M_MKWORKSPACE</span>
<span class="n">M_MKACTIVITY</span>
<span class="n">M_BASELINE_CONTROL</span>
<span class="n">M_MERGE</span>
<span class="n">M_INVALID</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="apache.exists_config">
<tt class="descclassname">apache.</tt><tt class="descname">exists_config</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#apache.exists_config" title="Permalink to this definition">¶</a></dt>
<dd><p>This function returns True if the Apache server was launched with
the definition with the given <em>name</em>. This means that you can
test whether Apache was launched with the <tt class="docutils literal"><span class="pre">-DFOOBAR</span></tt> parameter
by calling <tt class="docutils literal"><span class="pre">apache.exists_config_define('FOOBAR')</span></tt>.</p>
</dd></dl>

<dl class="function">
<dt id="apache.stat">
<tt class="descclassname">apache.</tt><tt class="descname">stat</tt><big>(</big><em>fname</em>, <em>wanted</em><big>)</big><a class="headerlink" href="#apache.stat" title="Permalink to this definition">¶</a></dt>
<dd><p>This function returns an instance of an <tt class="docutils literal"><span class="pre">mp_finfo</span></tt> object
describing information related to the file with name <tt class="docutils literal"><span class="pre">fname</span></tt>.
The <tt class="docutils literal"><span class="pre">wanted</span></tt> argument describes the minimum attributes which
should be filled out. The resultant object can be assigned to the
<a class="reference internal" href="#apache.request.finfo" title="apache.request.finfo"><tt class="xref py py-attr docutils literal"><span class="pre">request.finfo</span></tt></a> attribute.</p>
</dd></dl>

<dl class="function">
<dt id="apache.register_cleanup">
<tt class="descclassname">apache.</tt><tt class="descname">register_cleanup</tt><big>(</big><em>callable</em><span class="optional">[</span>, <em>data</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.register_cleanup" title="Permalink to this definition">¶</a></dt>
<dd><p>Registers a cleanup that will be performed at child shutdown
time. Equivalent to <a class="reference internal" href="#apache.server.register_cleanup" title="apache.server.register_cleanup"><tt class="xref py py-func docutils literal"><span class="pre">server.register_cleanup()</span></tt></a>, except
that a request object is not required. <em>Warning:</em> do not pass
directly or indirectly a request object in the data
parameter. Since the callable will be called at server shutdown
time, the request object won&#8217;t exist anymore and any manipulation
of it in the handler will give undefined behaviour.</p>
</dd></dl>

<dl class="function">
<dt id="apache.config_tree">
<tt class="descclassname">apache.</tt><tt class="descname">config_tree</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.config_tree" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the server-level configuration tree. This tree does not
include directives from .htaccess files. This is a <em>copy</em> of the
tree, modifying it has no effect on the actual configuration.</p>
</dd></dl>

<dl class="function">
<dt id="apache.server_root">
<tt class="descclassname">apache.</tt><tt class="descname">server_root</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.server_root" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the value of ServerRoot.</p>
</dd></dl>

<dl class="function">
<dt id="apache.make_table">
<tt class="descclassname">apache.</tt><tt class="descname">make_table</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.make_table" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is obsolete and is an alias to <a class="reference internal" href="#apache.table" title="apache.table"><tt class="xref py py-class docutils literal"><span class="pre">table</span></tt></a> (see below).</p>
</dd></dl>

<dl class="function">
<dt id="apache.mpm_query">
<tt class="descclassname">apache.</tt><tt class="descname">mpm_query</tt><big>(</big><em>code</em><big>)</big><a class="headerlink" href="#apache.mpm_query" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows querying of the MPM for various parameters such as numbers of
processes and threads. The return value is one of three constants:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">AP_MPMQ_NOT_SUPPORTED</span>      <span class="o">=</span> <span class="mi">0</span>  <span class="c"># This value specifies whether</span>
                                <span class="c"># an MPM is capable of</span>
                                <span class="c"># threading or forking.</span>
<span class="n">AP_MPMQ_STATIC</span>             <span class="o">=</span> <span class="mi">1</span>  <span class="c"># This value specifies whether</span>
                                <span class="c"># an MPM is using a static # of</span>
                                <span class="c"># threads or daemons.</span>
<span class="n">AP_MPMQ_DYNAMIC</span>            <span class="o">=</span> <span class="mi">2</span>  <span class="c"># This value specifies whether</span>
                                <span class="c"># an MPM is using a dynamic # of</span>
                                <span class="c"># threads or daemons.</span>
</pre></div>
</div>
<p>The <em>code</em> argument must be one of the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">AP_MPMQ_MAX_DAEMON_USED</span>    <span class="o">=</span> <span class="mi">1</span>  <span class="c"># Max # of daemons used so far</span>
<span class="n">AP_MPMQ_IS_THREADED</span>        <span class="o">=</span> <span class="mi">2</span>  <span class="c"># MPM can do threading</span>
<span class="n">AP_MPMQ_IS_FORKED</span>          <span class="o">=</span> <span class="mi">3</span>  <span class="c"># MPM can do forking</span>
<span class="n">AP_MPMQ_HARD_LIMIT_DAEMONS</span> <span class="o">=</span> <span class="mi">4</span>  <span class="c"># The compiled max # daemons</span>
<span class="n">AP_MPMQ_HARD_LIMIT_THREADS</span> <span class="o">=</span> <span class="mi">5</span>  <span class="c"># The compiled max # threads</span>
<span class="n">AP_MPMQ_MAX_THREADS</span>        <span class="o">=</span> <span class="mi">6</span>  <span class="c"># # of threads/child by config</span>
<span class="n">AP_MPMQ_MIN_SPARE_DAEMONS</span>  <span class="o">=</span> <span class="mi">7</span>  <span class="c"># Min # of spare daemons</span>
<span class="n">AP_MPMQ_MIN_SPARE_THREADS</span>  <span class="o">=</span> <span class="mi">8</span>  <span class="c"># Min # of spare threads</span>
<span class="n">AP_MPMQ_MAX_SPARE_DAEMONS</span>  <span class="o">=</span> <span class="mi">9</span>  <span class="c"># Max # of spare daemons</span>
<span class="n">AP_MPMQ_MAX_SPARE_THREADS</span>  <span class="o">=</span> <span class="mi">10</span> <span class="c"># Max # of spare threads</span>
<span class="n">AP_MPMQ_MAX_REQUESTS_DAEMON</span><span class="o">=</span> <span class="mi">11</span> <span class="c"># Max # of requests per daemon</span>
<span class="n">AP_MPMQ_MAX_DAEMONS</span>        <span class="o">=</span> <span class="mi">12</span> <span class="c"># Max # of daemons by config</span>
</pre></div>
</div>
<p>Example:</p>
<div class="highlight-python"><pre>if apache.mpm_query(apache.AP_MPMQ_IS_THREADED):
    # do something
else:
    # do something else</pre>
</div>
</dd></dl>

</div>
<div class="section" id="attributes">
<span id="pyapi-apmem"></span><h3>Attributes<a class="headerlink" href="#attributes" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="apache.interpreter">
<tt class="descclassname">apache.</tt><tt class="descname">interpreter</tt><a class="headerlink" href="#apache.interpreter" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The name of the subinterpreter under which we&#8217;re running.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.main_server">
<tt class="descclassname">apache.</tt><tt class="descname">main_server</tt><a class="headerlink" href="#apache.main_server" title="Permalink to this definition">¶</a></dt>
<dd><p>A <tt class="docutils literal"><span class="pre">server</span></tt> object for the main server.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.MODULE_MAGIC_NUMBER_MAJOR">
<tt class="descclassname">apache.</tt><tt class="descname">MODULE_MAGIC_NUMBER_MAJOR</tt><a class="headerlink" href="#apache.MODULE_MAGIC_NUMBER_MAJOR" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. An internal to Apache version number useful to determine whether
certain features should be available. See <a class="reference internal" href="#apache.MODULE_MAGIC_NUMBER_MINOR" title="apache.MODULE_MAGIC_NUMBER_MINOR"><tt class="xref py py-attr docutils literal"><span class="pre">MODULE_MAGIC_NUMBER_MINOR</span></tt></a>.</p>
<p>Major API changes that could cause compatibility problems for older
modules such as structure size changes.  No binary compatibility is
possible across a change in the major version.</p>
<p><em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.MODULE_MAGIC_NUMBER_MINOR">
<tt class="descclassname">apache.</tt><tt class="descname">MODULE_MAGIC_NUMBER_MINOR</tt><a class="headerlink" href="#apache.MODULE_MAGIC_NUMBER_MINOR" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. An internal to Apache version number useful to determine whether
certain features should be available. See <a class="reference internal" href="#apache.MODULE_MAGIC_NUMBER_MAJOR" title="apache.MODULE_MAGIC_NUMBER_MAJOR"><tt class="xref py py-attr docutils literal"><span class="pre">MODULE_MAGIC_NUMBER_MAJOR</span></tt></a>.</p>
<p>Minor API changes that do not cause binary compatibility problems.</p>
<p><em>(Read-Only)</em></p>
</dd></dl>

</div>
<div class="section" id="table-object-mp-table">
<span id="pyapi-mptable"></span><h3>Table Object (mp_table)<a class="headerlink" href="#table-object-mp-table" title="Permalink to this headline">¶</a></h3>
<span class="target" id="index-6"></span><dl class="class">
<dt id="apache.table">
<em class="property">class </em><tt class="descclassname">apache.</tt><tt class="descname">table</tt><big>(</big><span class="optional">[</span><em>mapping-or-sequence</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.table" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a new empty object of type <tt class="docutils literal"><span class="pre">mp_table</span></tt>. See Section
<a class="reference internal" href="#pyapi-mptable"><em>Table Object (mp_table)</em></a> for description of the table object. The
<em>mapping-or-sequence</em> will be used to provide initial values for
the table.</p>
<p>The table object is a wrapper around the Apache APR table. The
table object behaves very much like a dictionary (including the
Python 2.2 features such as support of the <tt class="docutils literal"><span class="pre">in</span></tt> operator, etc.),
with the following differences:</p>
<ul class="simple">
<li>Both keys and values must be strings.</li>
<li>Key lookups are case-insensitive.</li>
<li>Duplicate keys are allowed (see <a class="reference internal" href="#apache.table.add" title="apache.table.add"><tt class="xref py py-meth docutils literal"><span class="pre">table.add()</span></tt></a> below). When there is
more than one value for a key, a subscript operation returns a list.</li>
</ul>
<p>Much of the information that Apache uses is stored in tables. For
example, <a class="reference internal" href="#apache.request.headers_in" title="apache.request.headers_in"><tt class="xref py py-meth docutils literal"><span class="pre">request.headers_in()</span></tt></a> and <a class="reference internal" href="#apache.request.headers_out" title="apache.request.headers_out"><tt class="xref py py-meth docutils literal"><span class="pre">request.headers_out()</span></tt></a>.</p>
<p>All the tables that mod_python provides inside the request object
are actual mappings to the Apache structures, so changing the
Python table also changes the underlying Apache table.</p>
<p>In addition to normal dictionary-like behavior, the table object
also has the following method:</p>
<dl class="method">
<dt id="apache.table.add">
<tt class="descname">add</tt><big>(</big><em>key</em>, <em>val</em><big>)</big><a class="headerlink" href="#apache.table.add" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows for creating duplicate keys, which is useful
when multiple headers, such as <cite>Set-Cookie:</cite> are required.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="request-object">
<span id="pyapi-mprequest"></span><h3>Request Object<a class="headerlink" href="#request-object" title="Permalink to this headline">¶</a></h3>
<p id="index-7">The request object is a Python mapping to the Apache <cite>request_rec</cite>
structure. When a handler is invoked, it is always passed a single
argument - the request object. For brevity, we often refer to it here
and throughout the code as <tt class="docutils literal"><span class="pre">req</span></tt>.</p>
<p>You can dynamically assign attributes to it as a way to communicate
between handlers.</p>
<div class="section" id="request-methods">
<span id="pyapi-mprequest-meth"></span><h4>Request Methods<a class="headerlink" href="#request-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="apache.request.add_cgi_vars">
<tt class="descclassname">request.</tt><tt class="descname">add_cgi_vars</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.add_cgi_vars" title="Permalink to this definition">¶</a></dt>
<dd><p>Calls Apache function <tt class="docutils literal"><span class="pre">ap_add_common_vars()</span></tt> followed some code
very similar to Apache <tt class="docutils literal"><span class="pre">ap_add_cgi_vars()</span></tt> with the exception of
calculating <tt class="docutils literal"><span class="pre">PATH_TRANSLATED</span></tt> value, thereby avoiding
sub-requests and filesystem access used in the <tt class="docutils literal"><span class="pre">ap_add_cgi_vars()</span></tt>
implementation.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.add_common_vars">
<tt class="descclassname">request.</tt><tt class="descname">add_common_vars</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.add_common_vars" title="Permalink to this definition">¶</a></dt>
<dd><p>Use of this method is discouraged, use
<a class="reference internal" href="#apache.request.add_cgi_vars" title="apache.request.add_cgi_vars"><tt class="xref py py-meth docutils literal"><span class="pre">request.add_cgi_vars()</span></tt></a> instead.</p>
<p>Calls the Apache <tt class="docutils literal"><span class="pre">ap_add_common_vars()</span></tt> function. After a call to
this method, <a class="reference internal" href="#apache.request.subprocess_env" title="apache.request.subprocess_env"><tt class="xref py py-attr docutils literal"><span class="pre">request.subprocess_env</span></tt></a> will contain <em>some</em> CGI
information.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.add_handler">
<tt class="descclassname">request.</tt><tt class="descname">add_handler</tt><big>(</big><em>htype</em>, <em>handler</em><span class="optional">[</span>, <em>dir</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.add_handler" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows dynamic handler registration. <em>htype</em> is a string
containing the name of any of the apache request (but not filter or
connection) handler directives,
e.g. <tt class="docutils literal"><span class="pre">'PythonHandler'</span></tt>. <em>handler</em> is a string containing the
name of the module and the handler function.  Optional <em>dir</em> is
a string containing the name of the directory to be added to the
pythonpath. If no directory is specified, then, if there is already
a handler of the same type specified, its directory is inherited,
otherwise the directory of the presently executing handler is
used. If there is a <tt class="docutils literal"><span class="pre">'PythonPath'</span></tt> directive in effect, then
<tt class="docutils literal"><span class="pre">sys.path</span></tt> will be set exactly according to it (no directories
added, the <em>dir</em> argument is ignored).</p>
<p>A handler added this way only persists throughout the life of the
request. It is possible to register more handlers while inside the
handler of the same type. One has to be careful as to not to create
an infinite loop this way.</p>
<p>Dynamic handler registration is a useful technique that allows the
code to dynamically decide what will happen next. A typical example
might be a <tt class="docutils literal"><span class="pre">PythonAuthenHandler</span></tt> that will assign different
<tt class="docutils literal"><span class="pre">PythonHandlers</span></tt> based on the authorization level, something
like:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">manager</span><span class="p">:</span>
   <span class="n">req</span><span class="o">.</span><span class="n">add_handler</span><span class="p">(</span><span class="s">&quot;PythonHandler&quot;</span><span class="p">,</span> <span class="s">&quot;menu::admin&quot;</span><span class="p">)</span>
<span class="k">else</span><span class="p">:</span>
   <span class="n">req</span><span class="o">.</span><span class="n">add_handler</span><span class="p">(</span><span class="s">&quot;PythonHandler&quot;</span><span class="p">,</span> <span class="s">&quot;menu::basic&quot;</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you pass this function an invalid handler, an exception will be
generated at the time an attempt is made to find the handler.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="apache.request.add_input_filter">
<tt class="descclassname">request.</tt><tt class="descname">add_input_filter</tt><big>(</big><em>filter_name</em><big>)</big><a class="headerlink" href="#apache.request.add_input_filter" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds the named filter into the input filter chain for the current
request.  The filter should be added before the first attempt to
read any data from the request.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.add_output_filter">
<tt class="descclassname">request.</tt><tt class="descname">add_output_filter</tt><big>(</big><em>filter_name</em><big>)</big><a class="headerlink" href="#apache.request.add_output_filter" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds the named filter into the output filter chain for the current
request.  The filter should be added before the first attempt to
write any data for the response.</p>
<p>Provided that all data written is being buffered and not flushed,
this could be used to add the &#8220;CONTENT_LENGTH&#8221; filter into the
chain of output filters. The purpose of the &#8220;CONTENT_LENGTH&#8221; filter
is to add a <tt class="docutils literal"><span class="pre">Content-Length:</span></tt> header to the response.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">req</span><span class="o">.</span><span class="n">add_output_filter</span><span class="p">(</span><span class="s">&quot;CONTENT_LENGTH&quot;</span><span class="p">)</span>
<span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;content&quot;</span><span class="p">,</span><span class="mi">0</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="apache.request.allow_methods">
<tt class="descclassname">request.</tt><tt class="descname">allow_methods</tt><big>(</big><em>methods</em><span class="optional">[</span>, <em>reset</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.allow_methods" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds methods to the <a class="reference internal" href="#apache.request.allowed_methods" title="apache.request.allowed_methods"><tt class="xref py py-meth docutils literal"><span class="pre">request.allowed_methods()</span></tt></a> list. This list
will be passed in <cite>Allowed:</cite> header if
<tt class="xref py py-const docutils literal"><span class="pre">HTTP_METHOD_NOT_ALLOWED</span></tt> or <tt class="xref py py-const docutils literal"><span class="pre">HTTP_NOT_IMPLEMENTED</span></tt>
is returned to the client. Note that Apache doesn&#8217;t do anything to
restrict the methods, this list is only used to construct the
header. The actual method-restricting logic has to be provided in
the handler code.</p>
<p><em>methods</em> is a sequence of strings. If <em>reset</em> is 1, then
the list of methods is first cleared.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.auth_name">
<tt class="descclassname">request.</tt><tt class="descname">auth_name</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.auth_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns AuthName setting.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.auth_type">
<tt class="descclassname">request.</tt><tt class="descname">auth_type</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.auth_type" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns AuthType setting.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.construct_url">
<tt class="descclassname">request.</tt><tt class="descname">construct_url</tt><big>(</big><em>uri</em><big>)</big><a class="headerlink" href="#apache.request.construct_url" title="Permalink to this definition">¶</a></dt>
<dd><p>This function returns a fully qualified URI string from the path
specified by uri, using the information stored in the request to
determine the scheme, server name and port. The port number is not
included in the string if it is the same as the default port 80.</p>
<p>For example, imagine that the current request is directed to the
virtual server www.modpython.org at port 80. Then supplying
<tt class="docutils literal"><span class="pre">'/index.html'</span></tt> will yield the string
<tt class="docutils literal"><span class="pre">'http://www.modpython.org/index.html'</span></tt>.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.discard_request_body">
<tt class="descclassname">request.</tt><tt class="descname">discard_request_body</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.discard_request_body" title="Permalink to this definition">¶</a></dt>
<dd><p>Tests for and reads any message body in the request, simply discarding
whatever it receives.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.document_root">
<tt class="descclassname">request.</tt><tt class="descname">document_root</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.document_root" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns DocumentRoot setting.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.get_basic_auth_pw">
<tt class="descclassname">request.</tt><tt class="descname">get_basic_auth_pw</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.get_basic_auth_pw" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a string containing the password when Basic authentication is
used.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.get_config">
<tt class="descclassname">request.</tt><tt class="descname">get_config</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.get_config" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a reference to the table object containing the mod_python
configuration in effect for this request except for
<tt class="docutils literal"><span class="pre">Python*Handler</span></tt> and <tt class="docutils literal"><span class="pre">PythonOption</span></tt> (The latter can be obtained
via <a class="reference internal" href="#apache.request.get_options" title="apache.request.get_options"><tt class="xref py py-meth docutils literal"><span class="pre">request.get_options()</span></tt></a>. The table has directives as keys,
and their values, if any, as values.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.get_remote_host">
<tt class="descclassname">request.</tt><tt class="descname">get_remote_host</tt><big>(</big><span class="optional">[</span><em>type</em><span class="optional">[</span>, <em>str_is_ip</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.get_remote_host" title="Permalink to this definition">¶</a></dt>
<dd><p>This method is used to determine remote client&#8217;s DNS name or IP
number. The first call to this function may entail a DNS look up,
but subsequent calls will use the cached result from the first
call.</p>
<p>The optional <em>type</em> argument can specify the following:</p>
<ul class="simple">
<li><tt class="xref py py-const docutils literal"><span class="pre">apache.REMOTE_HOST</span></tt> Look up the DNS name. Return None if Apache
directive <tt class="docutils literal"><span class="pre">HostNameLookups</span></tt> is <tt class="docutils literal"><span class="pre">Off</span></tt> or the hostname cannot
be determined.</li>
<li><tt class="xref py py-const docutils literal"><span class="pre">apache.REMOTE_NAME</span></tt> <em>(Default)</em> Return the DNS name if
possible, or the IP (as a string in dotted decimal notation)
otherwise.</li>
<li><tt class="xref py py-const docutils literal"><span class="pre">apache.REMOTE_NOLOOKUP</span></tt> Don&#8217;t perform a DNS lookup, return an
IP. Note: if a lookup was performed prior to this call, then the
cached host name is returned.</li>
<li><tt class="xref py py-const docutils literal"><span class="pre">apache.REMOTE_DOUBLE_REV</span></tt> Force a double-reverse lookup. On
failure, return None.</li>
</ul>
<p>If <em>str_is_ip</em> is <tt class="xref docutils literal"><span class="pre">None</span></tt> or unspecified, then the return
value is a string representing the DNS name or IP address.</p>
<p>If the optional <em>str_is_ip</em> argument is not <tt class="xref docutils literal"><span class="pre">None</span></tt>, then
the return value is an <tt class="docutils literal"><span class="pre">(address,</span> <span class="pre">str_is_ip)</span></tt> tuple, where
<tt class="docutils literal"><span class="pre">str_is_ip</span></tt> is non-zero if <tt class="docutils literal"><span class="pre">address</span></tt> is an IP address
string.</p>
<p>On failure, <tt class="xref docutils literal"><span class="pre">None</span></tt> is returned.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.get_options">
<tt class="descclassname">request.</tt><tt class="descname">get_options</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.get_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a reference to the table object containing the options set by
the <tt class="docutils literal"><span class="pre">PythonOption</span></tt> directives.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.internal_redirect">
<tt class="descclassname">request.</tt><tt class="descname">internal_redirect</tt><big>(</big><em>new_uri</em><big>)</big><a class="headerlink" href="#apache.request.internal_redirect" title="Permalink to this definition">¶</a></dt>
<dd><p>Internally redirects the request to the <em>new_uri</em>. <em>new_uri</em>
must be a string.</p>
<p>The httpd server handles internal redirection by creating a new
request object and processing all request phases. Within an
internal redirect, <a class="reference internal" href="#apache.request.prev" title="apache.request.prev"><tt class="xref py py-meth docutils literal"><span class="pre">request.prev()</span></tt></a> will contain a reference to a
request object from which it was redirected.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.is_https">
<tt class="descclassname">request.</tt><tt class="descname">is_https</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.is_https" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns non-zero if the connection is using SSL/TLS. Will always return
zero if the mod_ssl Apache module is not loaded.</p>
<p>You can use this method during any request phase, unlike looking
for the <tt class="docutils literal"><span class="pre">HTTPS</span></tt> variable in the <a class="reference internal" href="#apache.request.subprocess_env" title="apache.request.subprocess_env"><tt class="xref py py-attr docutils literal"><span class="pre">request.subprocess_env</span></tt></a> member
dictionary.  This makes it possible to write an authentication or
access handler that makes decisions based upon whether SSL is being
used.</p>
<p>Note that this method will not determine the quality of the
encryption being used.  For that you should call the
<cite>ssl_var_lookup</cite> method to get one of the <cite>SSL_CIPHER*</cite> variables.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.log_error">
<tt class="descclassname">request.</tt><tt class="descname">log_error</tt><big>(</big><em>message</em><span class="optional">[</span>, <em>level</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.log_error" title="Permalink to this definition">¶</a></dt>
<dd><p>An interface to the Apache <cite>ap_log_rerror</cite> function. <em>message</em> is a
string with the error message, <em>level</em> is one of the following
flags constants:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">APLOG_EMERG</span>
<span class="n">APLOG_ALERT</span>
<span class="n">APLOG_CRIT</span>
<span class="n">APLOG_ERR</span>
<span class="n">APLOG_WARNING</span>
<span class="n">APLOG_NOTICE</span>
<span class="n">APLOG_INFO</span>
<span class="n">APLOG_DEBUG</span>
<span class="n">APLOG_NOERRNO</span>
</pre></div>
</div>
<p>If you need to write to log and do not have a reference to a request object,
use the <a class="reference internal" href="#apache.log_error" title="apache.log_error"><tt class="xref py py-func docutils literal"><span class="pre">apache.log_error()</span></tt></a> function.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.meets_conditions">
<tt class="descclassname">request.</tt><tt class="descname">meets_conditions</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.meets_conditions" title="Permalink to this definition">¶</a></dt>
<dd><p>Calls the Apache <tt class="docutils literal"><span class="pre">ap_meets_conditions()</span></tt> function which returns a
status code. If <em>status</em> is <tt class="xref py py-const docutils literal"><span class="pre">apache.OK</span></tt>, generate the
content of the response normally. If not, simply return <em>status</em>.
Note that <em>mtime</em> (and possibly the ETag header) should be set as
appropriate prior to calling this function. The same goes for
<a class="reference internal" href="#apache.request.status" title="apache.request.status"><tt class="xref py py-meth docutils literal"><span class="pre">request.status()</span></tt></a> if the status differs from <tt class="xref py py-const docutils literal"><span class="pre">apache.OK</span></tt>.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># ...</span>
<span class="n">r</span><span class="o">.</span><span class="n">headers_out</span><span class="p">[</span><span class="s">&#39;ETag&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s">&#39;&quot;1130794f-3774-4584-a4ea-0ab19e684268&quot;&#39;</span>
<span class="n">r</span><span class="o">.</span><span class="n">headers_out</span><span class="p">[</span><span class="s">&#39;Expires&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s">&#39;Mon, 18 Apr 2005 17:30:00 GMT&#39;</span>
<span class="n">r</span><span class="o">.</span><span class="n">update_mtime</span><span class="p">(</span><span class="mi">1000000000</span><span class="p">)</span>
<span class="n">r</span><span class="o">.</span><span class="n">set_last_modified</span><span class="p">()</span>

<span class="n">status</span> <span class="o">=</span> <span class="n">r</span><span class="o">.</span><span class="n">meets_conditions</span><span class="p">()</span>
<span class="k">if</span> <span class="n">status</span> <span class="o">!=</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span><span class="p">:</span>
   <span class="k">return</span> <span class="n">status</span>

<span class="c"># ... do expensive generation of the response content ...</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="apache.request.requires">
<tt class="descclassname">request.</tt><tt class="descname">requires</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.requires" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a tuple of strings of arguments to <tt class="docutils literal"><span class="pre">require</span></tt> directive.</p>
<p>For example, with the following apache configuration:</p>
<div class="highlight-python"><pre>AuthType Basic
require user joe
require valid-user</pre>
</div>
<p><a class="reference internal" href="#apache.request.requires" title="apache.request.requires"><tt class="xref py py-meth docutils literal"><span class="pre">request.requires()</span></tt></a> would return <tt class="docutils literal"><span class="pre">('user</span> <span class="pre">joe',</span> <span class="pre">'valid-user')</span></tt>.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.read">
<tt class="descclassname">request.</tt><tt class="descname">read</tt><big>(</big><span class="optional">[</span><em>len</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads at most <em>len</em> bytes directly from the client, returning a
string with the data read. If the <em>len</em> argument is negative or
omitted, reads all data given by the client.</p>
<p>This function is affected by the <tt class="docutils literal"><span class="pre">Timeout</span></tt> Apache
configuration directive. The read will be aborted and an
<tt class="xref py py-exc docutils literal"><span class="pre">IOError</span></tt> raised if the <tt class="xref py py-exc docutils literal"><span class="pre">Timeout</span></tt> is reached while
reading client data.</p>
<p>This function relies on the client providing the <tt class="docutils literal"><span class="pre">Content-length</span></tt>
header. Absence of the <tt class="docutils literal"><span class="pre">Content-length</span></tt> header will be treated as
if <tt class="docutils literal"><span class="pre">Content-length:</span> <span class="pre">0</span></tt> was supplied.</p>
<p>Incorrect <tt class="docutils literal"><span class="pre">Content-length</span></tt> may cause the function to try to read
more data than available, which will make the function block until
a <tt class="docutils literal"><span class="pre">Timeout</span></tt> is reached.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.readline">
<tt class="descclassname">request.</tt><tt class="descname">readline</tt><big>(</big><span class="optional">[</span><em>len</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#apache.request.read" title="apache.request.read"><tt class="xref py py-meth docutils literal"><span class="pre">request.read()</span></tt></a> but reads until end of line.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In accordance with the HTTP specification, most clients will be
terminating lines with <tt class="docutils literal"><span class="pre">'\r\n'</span></tt> rather than simply
<tt class="docutils literal"><span class="pre">'\n'</span></tt>.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="apache.request.readlines">
<tt class="descclassname">request.</tt><tt class="descname">readlines</tt><big>(</big><span class="optional">[</span><em>sizehint</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.readlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads all lines using <a class="reference internal" href="#apache.request.readline" title="apache.request.readline"><tt class="xref py py-meth docutils literal"><span class="pre">request.readline()</span></tt></a> and returns a list of
the lines read.  If the optional <em>sizehint</em> parameter is given in,
the method will read at least <em>sizehint</em> bytes of data, up to the
completion of the line in which the <em>sizehint</em> bytes limit is
reached.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.register_cleanup">
<tt class="descclassname">request.</tt><tt class="descname">register_cleanup</tt><big>(</big><em>callable</em><span class="optional">[</span>, <em>data</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.register_cleanup" title="Permalink to this definition">¶</a></dt>
<dd><p>Registers a cleanup. Argument <em>callable</em> can be any callable
object, the optional argument <em>data</em> can be any object (default is
<tt class="xref docutils literal"><span class="pre">None</span></tt>). At the very end of the request, just before the actual
request record is destroyed by Apache, <em>callable</em> will be
called with one argument, <em>data</em>.</p>
<p>It is OK to pass the request object as data, but keep in mind that
when the cleanup is executed, the request processing is already
complete, so doing things like writing to the client is completely
pointless.</p>
<p>If errors are encountered during cleanup processing, they should be
in error log, but otherwise will not affect request processing in
any way, which makes cleanup bugs sometimes hard to spot.</p>
<p>If the server is shut down before the cleanup had a chance to run,
it&#8217;s possible that it will not be executed.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.register_input_filter">
<tt class="descclassname">request.</tt><tt class="descname">register_input_filter</tt><big>(</big><em>filter_name</em>, <em>filter</em><span class="optional">[</span>, <em>dir</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.register_input_filter" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows dynamic registration of mod_python input
filters. <em>filter_name</em> is a string which would then subsequently be
used to identify the filter.  <em>filter</em> is a string containing
the name of the module and the filter function.  Optional <em>dir</em>
is a string containing the name of the directory to be added to the
pythonpath. If there is a <tt class="docutils literal"><span class="pre">PythonPath</span></tt> directive in effect,
then <tt class="docutils literal"><span class="pre">sys.path</span></tt> will be set exactly according to it (no
directories added, the <em>dir</em> argument is ignored).</p>
<p>The registration of the filter this way only persists for the life
of the request. To actually add the filter into the chain of input
filters for the current request <tt class="docutils literal"><span class="pre">request.add_input_filter()</span></tt> would be
used.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.register_output_filter">
<tt class="descclassname">request.</tt><tt class="descname">register_output_filter</tt><big>(</big><em>filter_name</em>, <em>filter</em><span class="optional">[</span>, <em>dir</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.register_output_filter" title="Permalink to this definition">¶</a></dt>
<dd><p>Allows dynamic registration of mod_python output
filters. <em>filter_name</em> is a string which would then subsequently be
used to identify the filter.  <em>filter</em> is a string containing the
name of the module and the filter function. Optional <em>dir</em> is a
string containing the name of the directory to be added to the
pythonpath. If there is a <tt class="docutils literal"><span class="pre">PythonPath</span></tt> directive in effect, then
<tt class="docutils literal"><span class="pre">sys.path</span></tt> will be set exactly according to it (no directories
added, the <em>dir</em> argument is ignored).</p>
<p>The registration of the filter this way only persists for the life
of the request. To actually add the filter into the chain of output
filters for the current request <a class="reference internal" href="#apache.request.add_output_filter" title="apache.request.add_output_filter"><tt class="xref py py-meth docutils literal"><span class="pre">request.add_output_filter()</span></tt></a>
would be used.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.sendfile">
<tt class="descclassname">request.</tt><tt class="descname">sendfile</tt><big>(</big><em>path</em><span class="optional">[</span>, <em>offset</em>, <em>len</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.sendfile" title="Permalink to this definition">¶</a></dt>
<dd><p>Sends <em>len</em> bytes of file <em>path</em> directly to the client, starting
at offset <em>offset</em> using the server&#8217;s internal API. <em>offset</em>
defaults to 0, and <em>len</em> defaults to -1 (send the entire file).</p>
<p>Returns the number of bytes sent, or raises an IOError exception on
failure.</p>
<p>This function provides the most efficient way to send a file to the
client.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.set_etag">
<tt class="descclassname">request.</tt><tt class="descname">set_etag</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.set_etag" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets the outgoing <tt class="docutils literal"><span class="pre">'ETag'</span></tt> header.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.set_last_modified">
<tt class="descclassname">request.</tt><tt class="descname">set_last_modified</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.set_last_modified" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets the outgoing <tt class="docutils literal"><span class="pre">Last-Modified</span></tt> header based on value of
<tt class="docutils literal"><span class="pre">mtime</span></tt> attribute.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.ssl_var_lookup">
<tt class="descclassname">request.</tt><tt class="descname">ssl_var_lookup</tt><big>(</big><em>var_name</em><big>)</big><a class="headerlink" href="#apache.request.ssl_var_lookup" title="Permalink to this definition">¶</a></dt>
<dd><p>Looks up the value of the named SSL variable.  This method queries
the mod_ssl Apache module directly, and may therefore be used in
early request phases (unlike using the <a class="reference internal" href="#apache.request.subprocess_env" title="apache.request.subprocess_env"><tt class="xref py py-attr docutils literal"><span class="pre">request.subprocess_env</span></tt></a>
member.</p>
<p>If the mod_ssl Apache module is not loaded or the variable is not
found then <tt class="xref docutils literal"><span class="pre">None</span></tt> is returned.</p>
<p>If you just want to know if a SSL or TLS connection is being used,
you may consider calling the <tt class="docutils literal"><span class="pre">is_https</span></tt> method instead.</p>
<p>It is unfortunately not possible to get a list of all available
variables with the current mod_ssl implementation, so you must know
the name of the variable you want.  Some of the potentially useful
ssl variables are listed below.  For a complete list of variables
and a description of their values see the mod_ssl documentation.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">SSL_CIPHER</span>
<span class="n">SSL_CLIENT_CERT</span>
<span class="n">SSL_CLIENT_VERIFY</span>
<span class="n">SSL_PROTOCOL</span>
<span class="n">SSL_SESSION_ID</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Not all SSL variables are defined or have useful values in every
request phase.  Also use caution when relying on these values
for security purposes, as SSL or TLS protocol parameters can
often be renegotiated at any time during a request.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="apache.request.update_mtime">
<tt class="descclassname">request.</tt><tt class="descname">update_mtime</tt><big>(</big><em>dependency_mtime</em><big>)</big><a class="headerlink" href="#apache.request.update_mtime" title="Permalink to this definition">¶</a></dt>
<dd><p>If <em>ependency_mtime</em> is later than the value in the <tt class="docutils literal"><span class="pre">mtime</span></tt>
attribute, sets the attribute to the new value.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.write">
<tt class="descclassname">request.</tt><tt class="descname">write</tt><big>(</big><em>string</em><span class="optional">[</span>, <em>flush=1</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.request.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Writes <em>string</em> directly to the client, then flushes the buffer,
unless flush is 0.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.flush">
<tt class="descclassname">request.</tt><tt class="descname">flush</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.request.flush" title="Permalink to this definition">¶</a></dt>
<dd><p>Flushes the output buffer.</p>
</dd></dl>

<dl class="method">
<dt id="apache.request.set_content_length">
<tt class="descclassname">request.</tt><tt class="descname">set_content_length</tt><big>(</big><em>len</em><big>)</big><a class="headerlink" href="#apache.request.set_content_length" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets the value of <a class="reference internal" href="#apache.request.clength" title="apache.request.clength"><tt class="xref py py-attr docutils literal"><span class="pre">request.clength</span></tt></a> and the <tt class="docutils literal"><span class="pre">'Content-Length'</span></tt>
header to len. Note that after the headers have been sent out
(which happens just before the first byte of the body is written,
i.e. first call to <a class="reference internal" href="#apache.request.write" title="apache.request.write"><tt class="xref py py-meth docutils literal"><span class="pre">request.write()</span></tt></a>), calling the method is
meaningless.</p>
</dd></dl>

</div>
<div class="section" id="request-members">
<span id="pyapi-mprequest-mem"></span><h4>Request Members<a class="headerlink" href="#request-members" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="apache.request.connection">
<tt class="descclassname">request.</tt><tt class="descname">connection</tt><a class="headerlink" href="#apache.request.connection" title="Permalink to this definition">¶</a></dt>
<dd><p>A <tt class="docutils literal"><span class="pre">connection</span></tt> object associated with this request. See
<a class="reference internal" href="#pyapi-mpconn"><em>Connection Object (mp_conn)</em></a> Object for more details.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.server">
<tt class="descclassname">request.</tt><tt class="descname">server</tt><a class="headerlink" href="#apache.request.server" title="Permalink to this definition">¶</a></dt>
<dd><p>A server object associated with this request. See
<a class="reference internal" href="#pyapi-mpserver"><em>Server Object (mp_server)</em></a> for more details.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.next">
<tt class="descclassname">request.</tt><tt class="descname">next</tt><a class="headerlink" href="#apache.request.next" title="Permalink to this definition">¶</a></dt>
<dd><p>If this is an internal redirect, the request object we redirect to.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.prev">
<tt class="descclassname">request.</tt><tt class="descname">prev</tt><a class="headerlink" href="#apache.request.prev" title="Permalink to this definition">¶</a></dt>
<dd><p>If this is an internal redirect, the request object we redirect from.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.main">
<tt class="descclassname">request.</tt><tt class="descname">main</tt><a class="headerlink" href="#apache.request.main" title="Permalink to this definition">¶</a></dt>
<dd><p>If this is a sub-request, pointer to the main request.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.the_request">
<tt class="descclassname">request.</tt><tt class="descname">the_request</tt><a class="headerlink" href="#apache.request.the_request" title="Permalink to this definition">¶</a></dt>
<dd><p>String containing the first line of the request.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.assbackwards">
<tt class="descclassname">request.</tt><tt class="descname">assbackwards</tt><a class="headerlink" href="#apache.request.assbackwards" title="Permalink to this definition">¶</a></dt>
<dd><p>Indicates an HTTP/0.9 &#8220;simple&#8221; request. This means that the
response will contain no headers, only the body. Although this
exists for backwards compatibility with obsolescent browsers, some
people have figured out that setting assbackwards to 1 can be a
useful technique when including part of the response from an
internal redirect to avoid headers being sent.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.proxyreq">
<tt class="descclassname">request.</tt><tt class="descname">proxyreq</tt><a class="headerlink" href="#apache.request.proxyreq" title="Permalink to this definition">¶</a></dt>
<dd><p>A proxy request: one of <tt class="xref py py-const docutils literal"><span class="pre">apache.PROXYREQ_*</span></tt> values.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.header_only">
<tt class="descclassname">request.</tt><tt class="descname">header_only</tt><a class="headerlink" href="#apache.request.header_only" title="Permalink to this definition">¶</a></dt>
<dd><p>A boolean value indicating HEAD request, as opposed to GET.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.protocol">
<tt class="descclassname">request.</tt><tt class="descname">protocol</tt><a class="headerlink" href="#apache.request.protocol" title="Permalink to this definition">¶</a></dt>
<dd><p>Protocol, as given by the client, or <tt class="docutils literal"><span class="pre">'HTTP/0.9'</span></tt>. Same as CGI <span class="target" id="index-8"></span><tt class="xref std std-envvar docutils literal"><span class="pre">SERVER_PROTOCOL</span></tt>.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.proto_num">
<tt class="descclassname">request.</tt><tt class="descname">proto_num</tt><a class="headerlink" href="#apache.request.proto_num" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Number version of protocol; 1.1 = 1001 <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.hostname">
<tt class="descclassname">request.</tt><tt class="descname">hostname</tt><a class="headerlink" href="#apache.request.hostname" title="Permalink to this definition">¶</a></dt>
<dd><p>String. Host, as set by full URI or Host: header.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.request_time">
<tt class="descclassname">request.</tt><tt class="descname">request_time</tt><a class="headerlink" href="#apache.request.request_time" title="Permalink to this definition">¶</a></dt>
<dd><p>A long integer. When request started.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.status_line">
<tt class="descclassname">request.</tt><tt class="descname">status_line</tt><a class="headerlink" href="#apache.request.status_line" title="Permalink to this definition">¶</a></dt>
<dd><p>Status line. E.g. <tt class="docutils literal"><span class="pre">'200</span> <span class="pre">OK'</span></tt>.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.status">
<tt class="descclassname">request.</tt><tt class="descname">status</tt><a class="headerlink" href="#apache.request.status" title="Permalink to this definition">¶</a></dt>
<dd><p>Status. One of <tt class="xref py py-const docutils literal"><span class="pre">apache.HTTP_*</span></tt> values.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.method">
<tt class="descclassname">request.</tt><tt class="descname">method</tt><a class="headerlink" href="#apache.request.method" title="Permalink to this definition">¶</a></dt>
<dd><p>A string containing the method - <tt class="docutils literal"><span class="pre">'GET'</span></tt>, <tt class="docutils literal"><span class="pre">'HEAD'</span></tt>, <tt class="docutils literal"><span class="pre">'POST'</span></tt>, etc.  Same
as CGI <span class="target" id="index-9"></span><tt class="xref std std-envvar docutils literal"><span class="pre">REQUEST_METHOD</span></tt>.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.method_number">
<tt class="descclassname">request.</tt><tt class="descname">method_number</tt><a class="headerlink" href="#apache.request.method_number" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer containing the method number.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.allowed">
<tt class="descclassname">request.</tt><tt class="descname">allowed</tt><a class="headerlink" href="#apache.request.allowed" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. A bitvector of the allowed methods. Used to construct the
Allowed: header when responding with
<tt class="xref py py-const docutils literal"><span class="pre">HTTP_METHOD_NOT_ALLOWED</span></tt> or
<tt class="xref py py-const docutils literal"><span class="pre">HTTP_NOT_IMPLEMENTED</span></tt>. This field is for Apache&#8217;s
internal use, to set the <tt class="docutils literal"><span class="pre">Allowed:</span></tt> methods use
<a class="reference internal" href="#apache.request.allow_methods" title="apache.request.allow_methods"><tt class="xref py py-meth docutils literal"><span class="pre">request.allow_methods()</span></tt></a> method, described in section
<a class="reference internal" href="#pyapi-mprequest-meth"><em>Request Methods</em></a>. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.allowed_xmethods">
<tt class="descclassname">request.</tt><tt class="descname">allowed_xmethods</tt><a class="headerlink" href="#apache.request.allowed_xmethods" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple. Allowed extension methods.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.allowed_methods">
<tt class="descclassname">request.</tt><tt class="descname">allowed_methods</tt><a class="headerlink" href="#apache.request.allowed_methods" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple. List of allowed methods. Used in relation with
<tt class="xref py py-const docutils literal"><span class="pre">METHOD_NOT_ALLOWED</span></tt>. This member can be modified via
<a class="reference internal" href="#apache.request.allow_methods" title="apache.request.allow_methods"><tt class="xref py py-meth docutils literal"><span class="pre">request.allow_methods()</span></tt></a> described in section
<a class="reference internal" href="#pyapi-mprequest-meth"><em>Request Methods</em></a>. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.sent_bodyct">
<tt class="descclassname">request.</tt><tt class="descname">sent_bodyct</tt><a class="headerlink" href="#apache.request.sent_bodyct" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Byte count in stream is for body. (?)  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.bytes_sent">
<tt class="descclassname">request.</tt><tt class="descname">bytes_sent</tt><a class="headerlink" href="#apache.request.bytes_sent" title="Permalink to this definition">¶</a></dt>
<dd><p>Long integer. Number of bytes sent.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.mtime">
<tt class="descclassname">request.</tt><tt class="descname">mtime</tt><a class="headerlink" href="#apache.request.mtime" title="Permalink to this definition">¶</a></dt>
<dd><p>Long integer. Time the resource was last modified.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.chunked">
<tt class="descclassname">request.</tt><tt class="descname">chunked</tt><a class="headerlink" href="#apache.request.chunked" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean value indicating when sending chunked transfer-coding.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.range">
<tt class="descclassname">request.</tt><tt class="descname">range</tt><a class="headerlink" href="#apache.request.range" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The <tt class="docutils literal"><span class="pre">Range:</span></tt> header.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.clength">
<tt class="descclassname">request.</tt><tt class="descname">clength</tt><a class="headerlink" href="#apache.request.clength" title="Permalink to this definition">¶</a></dt>
<dd><p>Long integer. The &#8220;real&#8221; content length.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.remaining">
<tt class="descclassname">request.</tt><tt class="descname">remaining</tt><a class="headerlink" href="#apache.request.remaining" title="Permalink to this definition">¶</a></dt>
<dd><p>Long integer. Bytes left to read. (Only makes sense inside a read
operation.)  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.read_length">
<tt class="descclassname">request.</tt><tt class="descname">read_length</tt><a class="headerlink" href="#apache.request.read_length" title="Permalink to this definition">¶</a></dt>
<dd><p>Long integer. Number of bytes read. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.read_body">
<tt class="descclassname">request.</tt><tt class="descname">read_body</tt><a class="headerlink" href="#apache.request.read_body" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. How the request body should be read. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.read_chunked">
<tt class="descclassname">request.</tt><tt class="descname">read_chunked</tt><a class="headerlink" href="#apache.request.read_chunked" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. Read chunked transfer coding.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.expecting_100">
<tt class="descclassname">request.</tt><tt class="descname">expecting_100</tt><a class="headerlink" href="#apache.request.expecting_100" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. Is client waiting for a 100 (<tt class="xref py py-const docutils literal"><span class="pre">HTTP_CONTINUE</span></tt>)
response.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.headers_in">
<tt class="descclassname">request.</tt><tt class="descname">headers_in</tt><a class="headerlink" href="#apache.request.headers_in" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#apache.table" title="apache.table"><tt class="xref py py-class docutils literal"><span class="pre">table</span></tt></a> object containing headers sent by the client.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.headers_out">
<tt class="descclassname">request.</tt><tt class="descname">headers_out</tt><a class="headerlink" href="#apache.request.headers_out" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#apache.table" title="apache.table"><tt class="xref py py-class docutils literal"><span class="pre">table</span></tt></a> object representing the headers to be sent to the
client.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.err_headers_out">
<tt class="descclassname">request.</tt><tt class="descname">err_headers_out</tt><a class="headerlink" href="#apache.request.err_headers_out" title="Permalink to this definition">¶</a></dt>
<dd><p>These headers get send with the error response, instead of
headers_out.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.subprocess_env">
<tt class="descclassname">request.</tt><tt class="descname">subprocess_env</tt><a class="headerlink" href="#apache.request.subprocess_env" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#apache.table" title="apache.table"><tt class="xref py py-class docutils literal"><span class="pre">table</span></tt></a> object containing environment information
typically usable for CGI.  You may have to call
<a class="reference internal" href="#apache.request.add_common_vars" title="apache.request.add_common_vars"><tt class="xref py py-meth docutils literal"><span class="pre">request.add_common_vars()</span></tt></a> and <a class="reference internal" href="#apache.request.add_cgi_vars" title="apache.request.add_cgi_vars"><tt class="xref py py-meth docutils literal"><span class="pre">request.add_cgi_vars()</span></tt></a>
first to fill in the information you need.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.notes">
<tt class="descclassname">request.</tt><tt class="descname">notes</tt><a class="headerlink" href="#apache.request.notes" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#apache.table" title="apache.table"><tt class="xref py py-class docutils literal"><span class="pre">table</span></tt></a> object that could be used to store miscellaneous
general purpose info that lives for as long as the request
lives. If you need to pass data between handlers, it&#8217;s better to
simply add members to the request object than to use
<a class="reference internal" href="#apache.request.notes" title="apache.request.notes"><tt class="xref py py-attr docutils literal"><span class="pre">request.notes</span></tt></a>.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.phase">
<tt class="descclassname">request.</tt><tt class="descname">phase</tt><a class="headerlink" href="#apache.request.phase" title="Permalink to this definition">¶</a></dt>
<dd><p>The phase currently being being processed,
e.g. <tt class="docutils literal"><span class="pre">'PythonHandler'</span></tt>.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.interpreter">
<tt class="descclassname">request.</tt><tt class="descname">interpreter</tt><a class="headerlink" href="#apache.request.interpreter" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of the subinterpreter under which we&#8217;re running.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.content_type">
<tt class="descclassname">request.</tt><tt class="descname">content_type</tt><a class="headerlink" href="#apache.request.content_type" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The content type. Mod_python maintains an internal flag
(<tt class="xref py py-attr docutils literal"><span class="pre">request._content_type_set</span></tt>) to keep track of whether
<a class="reference internal" href="#apache.request.content_type" title="apache.request.content_type"><tt class="xref py py-attr docutils literal"><span class="pre">request.content_type</span></tt></a> was set manually from within
Python. The publisher handler uses this flag in the following way:
when <a class="reference internal" href="#apache.request.content_type" title="apache.request.content_type"><tt class="xref py py-attr docutils literal"><span class="pre">request.content_type</span></tt></a> isn&#8217;t explicitly set, it attempts
to guess the content type by examining the first few bytes of the
output.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.content_languages">
<tt class="descclassname">request.</tt><tt class="descname">content_languages</tt><a class="headerlink" href="#apache.request.content_languages" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple. List of strings representing the content languages.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.handler">
<tt class="descclassname">request.</tt><tt class="descname">handler</tt><a class="headerlink" href="#apache.request.handler" title="Permalink to this definition">¶</a></dt>
<dd><p>The symbolic name of the content handler (as in module, not
mod_python handler) that will service the request during the
response phase. When the SetHandler/AddHandler directives are used
to trigger mod_python, this will be set to <tt class="docutils literal"><span class="pre">'mod_python'</span></tt> by
mod_mime. A mod_python handler executing prior to the response
phase may also set this to <tt class="docutils literal"><span class="pre">'mod_python'</span></tt> along with calling
<a class="reference internal" href="#apache.request.add_handler" title="apache.request.add_handler"><tt class="xref py py-meth docutils literal"><span class="pre">request.add_handler()</span></tt></a> to register a mod_python handler for
the response phase:</p>
<div class="highlight-python"><pre>def typehandler(req):
   if os.path.splitext(req.filename)[1] == ".py":
      req.handler = "mod_python"
     req.add_handler("PythonHandler", "mod_python.publisher")
     return apache.OK
   return apache.DECLINED</pre>
</div>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.content_encoding">
<tt class="descclassname">request.</tt><tt class="descname">content_encoding</tt><a class="headerlink" href="#apache.request.content_encoding" title="Permalink to this definition">¶</a></dt>
<dd><p>String. Content encoding.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.vlist_validator">
<tt class="descclassname">request.</tt><tt class="descname">vlist_validator</tt><a class="headerlink" href="#apache.request.vlist_validator" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Variant list validator (if negotiated).  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.user">
<tt class="descclassname">request.</tt><tt class="descname">user</tt><a class="headerlink" href="#apache.request.user" title="Permalink to this definition">¶</a></dt>
<dd><p>If an authentication check is made, this will hold the user
name. Same as CGI <span class="target" id="index-10"></span><tt class="xref std std-envvar docutils literal"><span class="pre">REMOTE_USER</span></tt>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><a class="reference internal" href="#apache.request.get_basic_auth_pw" title="apache.request.get_basic_auth_pw"><tt class="xref py py-meth docutils literal"><span class="pre">request.get_basic_auth_pw()</span></tt></a> must be called prior to using this value.</p>
</div>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.ap_auth_type">
<tt class="descclassname">request.</tt><tt class="descname">ap_auth_type</tt><a class="headerlink" href="#apache.request.ap_auth_type" title="Permalink to this definition">¶</a></dt>
<dd><p>Authentication type. Same as CGI <span class="target" id="index-11"></span><tt class="xref std std-envvar docutils literal"><span class="pre">AUTH_TYPE</span></tt>.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.no_cache">
<tt class="descclassname">request.</tt><tt class="descname">no_cache</tt><a class="headerlink" href="#apache.request.no_cache" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. This response cannot be cached.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.no_local_copy">
<tt class="descclassname">request.</tt><tt class="descname">no_local_copy</tt><a class="headerlink" href="#apache.request.no_local_copy" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. No local copy exists.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.unparsed_uri">
<tt class="descclassname">request.</tt><tt class="descname">unparsed_uri</tt><a class="headerlink" href="#apache.request.unparsed_uri" title="Permalink to this definition">¶</a></dt>
<dd><p>The URI without any parsing performed.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.uri">
<tt class="descclassname">request.</tt><tt class="descname">uri</tt><a class="headerlink" href="#apache.request.uri" title="Permalink to this definition">¶</a></dt>
<dd><p>The path portion of the URI.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.filename">
<tt class="descclassname">request.</tt><tt class="descname">filename</tt><a class="headerlink" href="#apache.request.filename" title="Permalink to this definition">¶</a></dt>
<dd><p>String. File name being requested.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.canonical_filename">
<tt class="descclassname">request.</tt><tt class="descname">canonical_filename</tt><a class="headerlink" href="#apache.request.canonical_filename" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The true filename (<a class="reference internal" href="#apache.request.filename" title="apache.request.filename"><tt class="xref py py-attr docutils literal"><span class="pre">request.filename</span></tt></a> is
canonicalized if they don&#8217;t match).</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.path_info">
<tt class="descclassname">request.</tt><tt class="descname">path_info</tt><a class="headerlink" href="#apache.request.path_info" title="Permalink to this definition">¶</a></dt>
<dd><p>String. What follows after the file name, but is before query args,
if anything. Same as CGI <span class="target" id="index-12"></span><tt class="xref std std-envvar docutils literal"><span class="pre">PATH_INFO</span></tt>.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.args">
<tt class="descclassname">request.</tt><tt class="descname">args</tt><a class="headerlink" href="#apache.request.args" title="Permalink to this definition">¶</a></dt>
<dd><p>String. Same as CGI <span class="target" id="index-13"></span><tt class="xref std std-envvar docutils literal"><span class="pre">QUERY_ARGS</span></tt>.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.finfo">
<tt class="descclassname">request.</tt><tt class="descname">finfo</tt><a class="headerlink" href="#apache.request.finfo" title="Permalink to this definition">¶</a></dt>
<dd><p>A file information object with type <tt class="docutils literal"><span class="pre">mp_finfo</span></tt>, analogous to the
result of the POSIX stat function, describing the file pointed to
by the URI. The object provides the attributes <tt class="docutils literal"><span class="pre">fname</span></tt>,
<tt class="docutils literal"><span class="pre">filetype</span></tt>, <tt class="docutils literal"><span class="pre">valid</span></tt>, <tt class="docutils literal"><span class="pre">protection</span></tt>, <tt class="docutils literal"><span class="pre">user</span></tt>, <tt class="docutils literal"><span class="pre">group</span></tt>, <tt class="docutils literal"><span class="pre">size</span></tt>,
<tt class="docutils literal"><span class="pre">inode</span></tt>, <tt class="docutils literal"><span class="pre">device</span></tt>, <tt class="docutils literal"><span class="pre">nlink</span></tt>, <tt class="docutils literal"><span class="pre">atime</span></tt>, <tt class="docutils literal"><span class="pre">mtime</span></tt>, <tt class="docutils literal"><span class="pre">ctime</span></tt> and
<tt class="docutils literal"><span class="pre">name</span></tt>.</p>
<p>The attribute may be assigned to using the result of
<a class="reference internal" href="#apache.stat" title="apache.stat"><tt class="xref py py-func docutils literal"><span class="pre">apache.stat()</span></tt></a>.  For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">req</span><span class="o">.</span><span class="n">finfo</span><span class="o">.</span><span class="n">filetype</span> <span class="o">==</span> <span class="n">apache</span><span class="o">.</span><span class="n">APR_DIR</span><span class="p">:</span>
  <span class="n">req</span><span class="o">.</span><span class="n">filename</span> <span class="o">=</span> <span class="n">posixpath</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">req</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="s">&#39;index.html&#39;</span><span class="p">)</span>
  <span class="n">req</span><span class="o">.</span><span class="n">finfo</span> <span class="o">=</span> <span class="n">apache</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">req</span><span class="o">.</span><span class="n">filename</span><span class="p">,</span> <span class="n">apache</span><span class="o">.</span><span class="n">APR_FINFO_MIN</span><span class="p">)</span>
</pre></div>
</div>
<p>For backward compatibility, the object can also be accessed as if
it were a tuple. The <tt class="docutils literal"><span class="pre">apache</span></tt> module defines a set of
<tt class="xref py py-const docutils literal"><span class="pre">FINFO_*</span></tt> constants that should be used to access elements
of this tuple.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">user</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">finfo</span><span class="p">[</span><span class="n">apache</span><span class="o">.</span><span class="n">FINFO_USER</span><span class="p">]</span>
</pre></div>
</div>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.parsed_uri">
<tt class="descclassname">request.</tt><tt class="descname">parsed_uri</tt><a class="headerlink" href="#apache.request.parsed_uri" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple. The URI broken down into pieces. <tt class="docutils literal"><span class="pre">(scheme,</span> <span class="pre">hostinfo,</span> <span class="pre">user,</span> <span class="pre">password,</span> <span class="pre">hostname,</span> <span class="pre">port,</span> <span class="pre">path,</span> <span class="pre">query,</span> <span class="pre">fragment)</span></tt>.
The <a class="reference internal" href="#module-apache" title="apache: Access to Apache Internals."><tt class="xref py py-mod docutils literal"><span class="pre">apache</span></tt></a> module defines a set of <tt class="xref py py-const docutils literal"><span class="pre">URI_*</span></tt> constants that
should be used to access elements of this tuple. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">fname</span> <span class="o">=</span> <span class="n">req</span><span class="o">.</span><span class="n">parsed_uri</span><span class="p">[</span><span class="n">apache</span><span class="o">.</span><span class="n">URI_PATH</span><span class="p">]</span>
</pre></div>
</div>
<p><em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.used_path_info">
<tt class="descclassname">request.</tt><tt class="descname">used_path_info</tt><a class="headerlink" href="#apache.request.used_path_info" title="Permalink to this definition">¶</a></dt>
<dd><p>Flag to accept or reject path_info on current request.</p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.eos_sent">
<tt class="descclassname">request.</tt><tt class="descname">eos_sent</tt><a class="headerlink" href="#apache.request.eos_sent" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. EOS bucket sent.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.useragent_addr">
<tt class="descclassname">request.</tt><tt class="descname">useragent_addr</tt><a class="headerlink" href="#apache.request.useragent_addr" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Apache 2.4 only</em></p>
<p>The (address, port) tuple for the user agent.</p>
<p>This attribute should reflect the address of the user agent and
not necessarily the other end of the TCP connection, for which
there is <a class="reference internal" href="#apache.connection.client_addr" title="apache.connection.client_addr"><tt class="xref py py-attr docutils literal"><span class="pre">connection.client_addr</span></tt></a>.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.request.useragent_ip">
<tt class="descclassname">request.</tt><tt class="descname">useragent_ip</tt><a class="headerlink" href="#apache.request.useragent_ip" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Apache 2.4 only</em></p>
<p>String with the IP of the user agent. Same as CGI <span class="target" id="index-14"></span><tt class="xref std std-envvar docutils literal"><span class="pre">REMOTE_ADDR</span></tt>.</p>
<p>This attribute should reflect the address of the user agent and
not necessarily the other end of the TCP connection, for which
there is <a class="reference internal" href="#apache.connection.client_ip" title="apache.connection.client_ip"><tt class="xref py py-attr docutils literal"><span class="pre">connection.client_ip</span></tt></a>.
<em>(Read-Only)</em></p>
</dd></dl>

</div>
</div>
<div class="section" id="connection-object-mp-conn">
<span id="pyapi-mpconn"></span><h3>Connection Object (mp_conn)<a class="headerlink" href="#connection-object-mp-conn" title="Permalink to this headline">¶</a></h3>
<p id="index-15">The connection object is a Python mapping to the Apache
<tt class="xref c c-type docutils literal"><span class="pre">conn_rec</span></tt> structure.</p>
<div class="section" id="connection-methods">
<span id="pyapi-mpconn-meth"></span><h4>Connection Methods<a class="headerlink" href="#connection-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="apache.connection.log_error">
<tt class="descclassname">connection.</tt><tt class="descname">log_error</tt><big>(</big><em>message</em><span class="optional">[</span>, <em>level</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.connection.log_error" title="Permalink to this definition">¶</a></dt>
<dd><p>An interface to the Apache <tt class="docutils literal"><span class="pre">ap_log_cerror</span></tt> function. <em>message</em> is
a string with the error message, <em>level</em> is one of the following
flags constants:</p>
<div class="highlight-python"><pre>  APLOG_EMERG
  APLOG_ALERT
  APLOG_CRIT
  APLOG_ERR
  APLOG_WARNING
  APLOG_NOTICE
  APLOG_INFO
  APLOG_DEBUG
  APLOG_NOERRNO

If you need to write to log and do not have a reference to a connection or
request object, use the :func:`apache.log_error` function.</pre>
</div>
</dd></dl>

<dl class="method">
<dt id="apache.connection.read">
<tt class="descclassname">connection.</tt><tt class="descname">read</tt><big>(</big><span class="optional">[</span><em>length</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.connection.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads at most <em>length</em> bytes from the client. The read blocks
indefinitely until there is at least one byte to read. If length is
-1, keep reading until the socket is closed from the other end
(This is known as <tt class="docutils literal"><span class="pre">EXHAUSTIVE</span></tt> mode in the http server code).</p>
<p>This method should only be used inside <em>Connection Handlers</em>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The behavior of this method has changed since version 3.0.3. In
3.0.3 and prior, this method would block until <em>length</em> bytes
was read.</p>
</div>
</dd></dl>

<dl class="method">
<dt id="apache.connection.readline">
<tt class="descclassname">connection.</tt><tt class="descname">readline</tt><big>(</big><span class="optional">[</span><em>length</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.connection.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads a line from the connection or up to <em>length</em> bytes.</p>
<p>This method should only be used inside <em>Connection Handlers</em>.</p>
</dd></dl>

<dl class="method">
<dt id="apache.connection.write">
<tt class="descclassname">connection.</tt><tt class="descname">write</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#apache.connection.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Writes <em>string</em> to the client.</p>
<p>This method should only be used inside <em>Connection Handlers</em>.</p>
</dd></dl>

</div>
<div class="section" id="connection-members">
<span id="pyapi-mpconn-mem"></span><h4>Connection Members<a class="headerlink" href="#connection-members" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="apache.connection.base_server">
<tt class="descclassname">connection.</tt><tt class="descname">base_server</tt><a class="headerlink" href="#apache.connection.base_server" title="Permalink to this definition">¶</a></dt>
<dd><p>A <tt class="docutils literal"><span class="pre">server</span></tt> object for the physical vhost that this connection came
in through.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.local_addr">
<tt class="descclassname">connection.</tt><tt class="descname">local_addr</tt><a class="headerlink" href="#apache.connection.local_addr" title="Permalink to this definition">¶</a></dt>
<dd><p>The (address, port) tuple for the server.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.remote_addr">
<tt class="descclassname">connection.</tt><tt class="descname">remote_addr</tt><a class="headerlink" href="#apache.connection.remote_addr" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Deprecated in Apache 2.4, use client_addr. (Aliased to client_addr for backward compatibility)</em></p>
<p>The (address, port) tuple for the client.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.client_addr">
<tt class="descclassname">connection.</tt><tt class="descname">client_addr</tt><a class="headerlink" href="#apache.connection.client_addr" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Apache 2.4 only</em></p>
<p>The (address, port) tuple for the client.</p>
<p>This attribute reflects the other end of the TCP connection, which
may not always be the address of the user agent. A more accurate
source of the user agent address is <a class="reference internal" href="#apache.request.useragent_addr" title="apache.request.useragent_addr"><tt class="xref py py-attr docutils literal"><span class="pre">request.useragent_addr</span></tt></a>.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.remote_ip">
<tt class="descclassname">connection.</tt><tt class="descname">remote_ip</tt><a class="headerlink" href="#apache.connection.remote_ip" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Deprecated in Apache 2.4, use client_ip. (Aliased to client_ip for backward compatibility)</em></p>
<p>String with the IP of the client. In Apache 2.2 same as CGI <span class="target" id="index-16"></span><tt class="xref std std-envvar docutils literal"><span class="pre">REMOTE_ADDR</span></tt>.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.client_ip">
<tt class="descclassname">connection.</tt><tt class="descname">client_ip</tt><a class="headerlink" href="#apache.connection.client_ip" title="Permalink to this definition">¶</a></dt>
<dd><p><em>Apache 2.4 only</em></p>
<p>String with the IP of the client.</p>
<p>This attribute reflects the other end of the TCP connection, which
may not always be the address of the user agent. A more accurate
source of the user agent address is <a class="reference internal" href="#apache.request.useragent_ip" title="apache.request.useragent_ip"><tt class="xref py py-attr docutils literal"><span class="pre">request.useragent_ip</span></tt></a>.</p>
<p><em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.remote_host">
<tt class="descclassname">connection.</tt><tt class="descname">remote_host</tt><a class="headerlink" href="#apache.connection.remote_host" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The DNS name of the remote client. None if DNS has not been
checked, <tt class="docutils literal"><span class="pre">''</span></tt> (empty string) if no name found. Same as CGI
<span class="target" id="index-17"></span><tt class="xref std std-envvar docutils literal"><span class="pre">REMOTE_HOST</span></tt>.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.remote_logname">
<tt class="descclassname">connection.</tt><tt class="descname">remote_logname</tt><a class="headerlink" href="#apache.connection.remote_logname" title="Permalink to this definition">¶</a></dt>
<dd><p>Remote name if using <span class="target" id="index-18"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc1413.html"><strong>RFC 1413</strong></a> (ident). Same as CGI
<span class="target" id="index-19"></span><tt class="xref std std-envvar docutils literal"><span class="pre">REMOTE_IDENT</span></tt>.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.aborted">
<tt class="descclassname">connection.</tt><tt class="descname">aborted</tt><a class="headerlink" href="#apache.connection.aborted" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. True is the connection is aborted. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.keepalive">
<tt class="descclassname">connection.</tt><tt class="descname">keepalive</tt><a class="headerlink" href="#apache.connection.keepalive" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. 1 means the connection will be kept for the next request,
0 means &#8220;undecided&#8221;, -1 means &#8220;fatal error&#8221;.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.double_reverse">
<tt class="descclassname">connection.</tt><tt class="descname">double_reverse</tt><a class="headerlink" href="#apache.connection.double_reverse" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. 1 means double reverse DNS lookup has been performed, 0
means not yet, -1 means yes and it failed.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.keepalives">
<tt class="descclassname">connection.</tt><tt class="descname">keepalives</tt><a class="headerlink" href="#apache.connection.keepalives" title="Permalink to this definition">¶</a></dt>
<dd><p>The number of times this connection has been used. (?)
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.local_ip">
<tt class="descclassname">connection.</tt><tt class="descname">local_ip</tt><a class="headerlink" href="#apache.connection.local_ip" title="Permalink to this definition">¶</a></dt>
<dd><p>String with the IP of the server. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.local_host">
<tt class="descclassname">connection.</tt><tt class="descname">local_host</tt><a class="headerlink" href="#apache.connection.local_host" title="Permalink to this definition">¶</a></dt>
<dd><p>DNS name of the server. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.id">
<tt class="descclassname">connection.</tt><tt class="descname">id</tt><a class="headerlink" href="#apache.connection.id" title="Permalink to this definition">¶</a></dt>
<dd><p>Long. A unique connection id. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.connection.notes">
<tt class="descclassname">connection.</tt><tt class="descname">notes</tt><a class="headerlink" href="#apache.connection.notes" title="Permalink to this definition">¶</a></dt>
<dd><p>A <a class="reference internal" href="#apache.table" title="apache.table"><tt class="xref py py-class docutils literal"><span class="pre">table</span></tt></a> object containing miscellaneous general purpose
info that lives for as long as the connection lives.</p>
</dd></dl>

</div>
</div>
<div class="section" id="filter-object-mp-filter">
<span id="pyapi-mpfilt"></span><h3>Filter Object (mp_filter)<a class="headerlink" href="#filter-object-mp-filter" title="Permalink to this headline">¶</a></h3>
<p id="index-20">A filter object is passed to mod_python input and output filters. It
is used to obtain filter information, as well as get and pass
information to adjacent filters in the filter stack.</p>
<div class="section" id="filter-methods">
<span id="pyapi-mpfilt-meth"></span><h4>Filter Methods<a class="headerlink" href="#filter-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="apache.filter.pass_on">
<tt class="descclassname">filter.</tt><tt class="descname">pass_on</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.filter.pass_on" title="Permalink to this definition">¶</a></dt>
<dd><p>Passes all data through the filter without any processing.</p>
</dd></dl>

<dl class="method">
<dt id="apache.filter.read">
<tt class="descclassname">filter.</tt><tt class="descname">read</tt><big>(</big><span class="optional">[</span><em>length</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.filter.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads at most <em>len</em> bytes from the next filter, returning a
string with the data read or None if End Of Stream (EOS) has been
reached. A filter <em>must</em> be closed once the EOS has been
encountered.</p>
<p>If the <em>length</em> argument is negative or omitted, reads all data
currently available.</p>
</dd></dl>

<dl class="method">
<dt id="apache.filter.readline">
<tt class="descclassname">filter.</tt><tt class="descname">readline</tt><big>(</big><span class="optional">[</span><em>length</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.filter.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Reads a line from the next filter or up to <em>length</em> bytes.</p>
</dd></dl>

<dl class="method">
<dt id="apache.filter.write">
<tt class="descclassname">filter.</tt><tt class="descname">write</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#apache.filter.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Writes <em>string</em> to the next filter.</p>
</dd></dl>

<dl class="method">
<dt id="apache.filte.flush">
<tt class="descclassname">filte.</tt><tt class="descname">flush</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.filte.flush" title="Permalink to this definition">¶</a></dt>
<dd><p>Flushes the output by sending a FLUSH bucket.</p>
</dd></dl>

<dl class="method">
<dt id="apache.filter.close">
<tt class="descclassname">filter.</tt><tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.filter.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Closes the filter and sends an EOS bucket. Any further IO
operations on this filter will throw an exception.</p>
</dd></dl>

<dl class="method">
<dt id="apache.filter.disable">
<tt class="descclassname">filter.</tt><tt class="descname">disable</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.filter.disable" title="Permalink to this definition">¶</a></dt>
<dd><p>Tells mod_python to ignore the provided handler and just pass the
data on. Used internally by mod_python to print traceback from
exceptions encountered in filter handlers to avoid an infinite
loop.</p>
</dd></dl>

</div>
<div class="section" id="filter-members">
<span id="pyapi-mpfilt-mem"></span><h4>Filter Members<a class="headerlink" href="#filter-members" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="apache.filter.closed">
<tt class="descclassname">filter.</tt><tt class="descname">closed</tt><a class="headerlink" href="#apache.filter.closed" title="Permalink to this definition">¶</a></dt>
<dd><p>A boolean value indicating whether a filter is closed.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.filter.name">
<tt class="descclassname">filter.</tt><tt class="descname">name</tt><a class="headerlink" href="#apache.filter.name" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The name under which this filter is registered.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.filter.req">
<tt class="descclassname">filter.</tt><tt class="descname">req</tt><a class="headerlink" href="#apache.filter.req" title="Permalink to this definition">¶</a></dt>
<dd><p>A reference to the request object.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.filter.is_input">
<tt class="descclassname">filter.</tt><tt class="descname">is_input</tt><a class="headerlink" href="#apache.filter.is_input" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. True if this is an input filter.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.filter.handler">
<tt class="descclassname">filter.</tt><tt class="descname">handler</tt><a class="headerlink" href="#apache.filter.handler" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The name of the Python handler for this filter as specified
in the configuration.  <em>(Read-Only)</em></p>
</dd></dl>

</div>
<div class="section" id="server-object-mp-server">
<span id="pyapi-mpserver"></span><h4>Server Object (mp_server)<a class="headerlink" href="#server-object-mp-server" title="Permalink to this headline">¶</a></h4>
<p id="index-21">The request object is a Python mapping to the Apache
<tt class="docutils literal"><span class="pre">request_rec</span></tt> structure. The server structure describes the
server (possibly virtual server) serving the request.</p>
</div>
<div class="section" id="server-methods">
<span id="pyapi-mpsrv-meth"></span><h4>Server Methods<a class="headerlink" href="#server-methods" title="Permalink to this headline">¶</a></h4>
<dl class="method">
<dt id="apache.server.get_config">
<tt class="descclassname">server.</tt><tt class="descname">get_config</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.server.get_config" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#apache.request.get_config" title="apache.request.get_config"><tt class="xref py py-meth docutils literal"><span class="pre">request.get_config()</span></tt></a>, but returns a table object
holding only the mod_python configuration defined at global scope
within the Apache configuration. That is, outside of the context of
any VirtualHost, Location, Directory or Files directives.</p>
</dd></dl>

<dl class="method">
<dt id="apache.server.get_options">
<tt class="descclassname">server.</tt><tt class="descname">get_options</tt><big>(</big><big>)</big><a class="headerlink" href="#apache.server.get_options" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#apache.request.get_options" title="apache.request.get_options"><tt class="xref py py-meth docutils literal"><span class="pre">request.get_options()</span></tt></a>, but returns a table
object holding only the mod_python options defined at global scope
within the Apache configuration. That is, outside of the context of
any VirtualHost, Location, Directory or Files directives.</p>
</dd></dl>

<dl class="method">
<dt id="apache.server.log_error">
<tt class="descclassname">server.</tt><tt class="descname">log_error</tt><big>(</big><em>message[level]</em><big>)</big><a class="headerlink" href="#apache.server.log_error" title="Permalink to this definition">¶</a></dt>
<dd><p>An interface to the Apache <tt class="docutils literal"><span class="pre">ap_log_error</span></tt> function. <em>message</em> is
a string with the error message, <em>level</em> is one of the following
flags constants:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">APLOG_EMERG</span>
<span class="n">APLOG_ALERT</span>
<span class="n">APLOG_CRIT</span>
<span class="n">APLOG_ERR</span>
<span class="n">APLOG_WARNING</span>
<span class="n">APLOG_NOTICE</span>
<span class="n">APLOG_INFO</span>
<span class="n">APLOG_DEBUG</span>
<span class="n">APLOG_NOERRNO</span>
</pre></div>
</div>
<p>If you need to write to log and do not have a reference to a server or
request object, use the <a class="reference internal" href="#apache.log_error" title="apache.log_error"><tt class="xref py py-func docutils literal"><span class="pre">apache.log_error()</span></tt></a> function.</p>
</dd></dl>

<dl class="method">
<dt id="apache.server.register_cleanup">
<tt class="descclassname">server.</tt><tt class="descname">register_cleanup</tt><big>(</big><em>request</em>, <em>callable</em><span class="optional">[</span>, <em>data</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#apache.server.register_cleanup" title="Permalink to this definition">¶</a></dt>
<dd><p>Registers a cleanup. Very similar to <tt class="xref py py-meth docutils literal"><span class="pre">req.register_cleanup()</span></tt>,
except this cleanup will be executed at child termination
time. This function requires the request object be supplied to
infer the interpreter name.  If you don&#8217;t have any request object
at hand, then you must use the <a class="reference internal" href="#apache.register_cleanup" title="apache.register_cleanup"><tt class="xref py py-func docutils literal"><span class="pre">apache.register_cleanup()</span></tt></a>
variant.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><em>Warning:</em> do not pass directly or indirectly a request object in
the data parameter. Since the callable will be called at server
shutdown time, the request object won&#8217;t exist anymore and any
manipulation of it in the callable will give undefined behaviour.</p>
</div>
</dd></dl>

</div>
<div class="section" id="server-members">
<span id="pyapi-mpsrv-mem"></span><h4>Server Members<a class="headerlink" href="#server-members" title="Permalink to this headline">¶</a></h4>
<dl class="attribute">
<dt id="apache.server.defn_name">
<tt class="descclassname">server.</tt><tt class="descname">defn_name</tt><a class="headerlink" href="#apache.server.defn_name" title="Permalink to this definition">¶</a></dt>
<dd><p>String. The name of the configuration file where the server
definition was found.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.defn_line_number">
<tt class="descclassname">server.</tt><tt class="descname">defn_line_number</tt><a class="headerlink" href="#apache.server.defn_line_number" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Line number in the config file where the server definition
is found.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.server_admin">
<tt class="descclassname">server.</tt><tt class="descname">server_admin</tt><a class="headerlink" href="#apache.server.server_admin" title="Permalink to this definition">¶</a></dt>
<dd><p>Value of the <tt class="docutils literal"><span class="pre">ServerAdmin</span></tt> directive.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.server_hostname">
<tt class="descclassname">server.</tt><tt class="descname">server_hostname</tt><a class="headerlink" href="#apache.server.server_hostname" title="Permalink to this definition">¶</a></dt>
<dd><p>Value of the <tt class="docutils literal"><span class="pre">ServerName</span></tt> directive. Same as CGI
<span class="target" id="index-22"></span><tt class="xref std std-envvar docutils literal"><span class="pre">SERVER_NAME</span></tt>. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.names">
<tt class="descclassname">server.</tt><tt class="descname">names</tt><a class="headerlink" href="#apache.server.names" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple. List of normal server names specified in the <tt class="docutils literal"><span class="pre">ServerAlias</span></tt>
directive.  This list does not include wildcarded names, which are
listed separately in <tt class="docutils literal"><span class="pre">wild_names</span></tt>. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.wild_names">
<tt class="descclassname">server.</tt><tt class="descname">wild_names</tt><a class="headerlink" href="#apache.server.wild_names" title="Permalink to this definition">¶</a></dt>
<dd><p>Tuple. List of wildcarded server names specified in the <tt class="docutils literal"><span class="pre">ServerAlias</span></tt>
directive. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.port">
<tt class="descclassname">server.</tt><tt class="descname">port</tt><a class="headerlink" href="#apache.server.port" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. TCP/IP port number. Same as CGI <span class="target" id="index-23"></span><tt class="xref std std-envvar docutils literal"><span class="pre">SERVER_PORT</span></tt>.
<em>This member appears to be 0 on Apache 2.0, look at
req.connection.local_addr instead</em> <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.error_fname">
<tt class="descclassname">server.</tt><tt class="descname">error_fname</tt><a class="headerlink" href="#apache.server.error_fname" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of the error log file for this server, if any.
<em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.loglevel">
<tt class="descclassname">server.</tt><tt class="descname">loglevel</tt><a class="headerlink" href="#apache.server.loglevel" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Logging level. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.is_virtual">
<tt class="descclassname">server.</tt><tt class="descname">is_virtual</tt><a class="headerlink" href="#apache.server.is_virtual" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean. True if this is a virtual server. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.timeout">
<tt class="descclassname">server.</tt><tt class="descname">timeout</tt><a class="headerlink" href="#apache.server.timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Value of the <tt class="docutils literal"><span class="pre">Timeout</span></tt> directive.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.keep_alive_timeout">
<tt class="descclassname">server.</tt><tt class="descname">keep_alive_timeout</tt><a class="headerlink" href="#apache.server.keep_alive_timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Keepalive timeout.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.keep_alive_max">
<tt class="descclassname">server.</tt><tt class="descname">keep_alive_max</tt><a class="headerlink" href="#apache.server.keep_alive_max" title="Permalink to this definition">¶</a></dt>
<dd><p>Maximum number of requests per keepalive.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.keep_alive">
<tt class="descclassname">server.</tt><tt class="descname">keep_alive</tt><a class="headerlink" href="#apache.server.keep_alive" title="Permalink to this definition">¶</a></dt>
<dd><p>Use persistent connections?  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.path">
<tt class="descclassname">server.</tt><tt class="descname">path</tt><a class="headerlink" href="#apache.server.path" title="Permalink to this definition">¶</a></dt>
<dd><p>String. Path for <tt class="docutils literal"><span class="pre">ServerPath</span></tt> <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.pathlen">
<tt class="descclassname">server.</tt><tt class="descname">pathlen</tt><a class="headerlink" href="#apache.server.pathlen" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Path length. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.limit_req_line">
<tt class="descclassname">server.</tt><tt class="descname">limit_req_line</tt><a class="headerlink" href="#apache.server.limit_req_line" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Limit on size of the HTTP request line. <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.limit_req_fieldsize">
<tt class="descclassname">server.</tt><tt class="descname">limit_req_fieldsize</tt><a class="headerlink" href="#apache.server.limit_req_fieldsize" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Limit on size of any request header field.  <em>(Read-Only)</em></p>
</dd></dl>

<dl class="attribute">
<dt id="apache.server.limit_req_fields">
<tt class="descclassname">server.</tt><tt class="descname">limit_req_fields</tt><a class="headerlink" href="#apache.server.limit_req_fields" title="Permalink to this definition">¶</a></dt>
<dd><p>Integer. Limit on number of request header fields.  <em>(Read-Only)</em></p>
</dd></dl>

</div>
</div>
</div>
<div class="section" id="module-util">
<span id="util-miscellaneous-utilities"></span><span id="pyapi-util"></span><h2><a class="reference internal" href="#module-util" title="util: Miscellaneous Utilities."><tt class="xref py py-mod docutils literal"><span class="pre">util</span></tt></a> &#8211; Miscellaneous Utilities<a class="headerlink" href="#module-util" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#module-util" title="util: Miscellaneous Utilities."><tt class="xref py py-mod docutils literal"><span class="pre">util</span></tt></a> module provides a number of utilities handy to a web
application developer similar to those in the standard library
<tt class="xref py py-mod docutils literal"><span class="pre">cgi</span></tt> module. The implementations in the <a class="reference internal" href="#module-util" title="util: Miscellaneous Utilities."><tt class="xref py py-mod docutils literal"><span class="pre">util</span></tt></a> module are
much more efficient because they call directly into Apache API&#8217;s as
opposed to using CGI which relies on the environment to pass
information.</p>
<p>The recommended way of using this module is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">util</span>
</pre></div>
</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><span class="target" id="index-24"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc3875.html"><strong>RFC 3875</strong></a></dt>
<dd>for detailed information on the CGI specification</dd>
</dl>
</div>
<div class="section" id="fieldstorage-class">
<span id="pyapi-util-fstor"></span><h3>FieldStorage class<a class="headerlink" href="#fieldstorage-class" title="Permalink to this headline">¶</a></h3>
<p>Access to form data is provided via the <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a>
class. This class is similar to the standard library module
<tt class="docutils literal"><span class="pre">cgi.FieldStorage</span></tt></p>
<dl class="class">
<dt id="util.FieldStorage">
<em class="property">class </em><tt class="descclassname">util.</tt><tt class="descname">FieldStorage</tt><big>(</big><em>req</em><span class="optional">[</span>, <em>keep_blank_values</em><span class="optional">[</span>, <em>strict_parsing</em><span class="optional">[</span>, <em>file_callback</em><span class="optional">[</span>, <em>field_callback</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#util.FieldStorage" title="Permalink to this definition">¶</a></dt>
<dd><p>This class provides uniform access to HTML form data submitted by
the client.  <em>req</em> is an instance of the mod_python
<tt class="xref py py-class docutils literal"><span class="pre">request</span></tt> object.</p>
<p>The optional argument <em>keep_blank_values</em> is a flag indicating
whether blank values in URL encoded form data should be treated as
blank strings. The default is false, which means that blank values
are ignored as if they were not included.</p>
<p>The optional argument <em>strict_parsing</em> is not yet implemented.</p>
<p>The optional argument <em>file_callback</em> allows the application to
override both file creation/deletion semantics and location. See
<a class="reference internal" href="#pyapi-util-fstor-examples"><em>FieldStorage Examples</em></a> for
additional information. <em>New in version 3.2</em></p>
<p>The optional argument <em>field_callback</em> allows the application to
override both the creation/deletion semantics and behavior. <em>New
in version 3.2</em></p>
<p>During initialization, <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> class reads all of the
data provided by the client. Since all data provided by the client
is consumed at this point, there should be no more than one
<a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> class instantiated per single request, nor
should you make any attempts to read client data before or after
instantiating a <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a>. A suggested strategy for
dealing with this is that any handler should first check for the
existence of a <tt class="docutils literal"><span class="pre">form</span></tt> attribute within the request object. If
this exists, it should be taken to be an existing instance of the
<a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> class and that should be used. If the
attribute does not exist and needs to be created, it should be
cached as the <tt class="docutils literal"><span class="pre">form</span></tt> attribute of the request object so later
handler code can use it.</p>
<p>When the <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> class instance is created, the data
read from the client is then parsed into separate fields and
packaged in <a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> objects, one per field. For HTML form
inputs of type <tt class="docutils literal"><span class="pre">file</span></tt>, a temporary file is created that can later
be accessed via the <a class="reference internal" href="#util.Field.file" title="util.Field.file"><tt class="xref py py-attr docutils literal"><span class="pre">Field.file</span></tt></a> attribute of a
<a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> object.</p>
<p>The <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> class has a mapping object interface,
i.e. it can be treated like a dictionary in most instances, but is
not strictly compatible as is it missing some methods provided by
dictionaries and some methods don&#8217;t behave entirely like their
counterparts, especially when there is more than one value
associated with a form field. When used as a mapping, the keys are
form input names, and the returned dictionary value can be:</p>
<ul class="simple">
<li>An instance of <tt class="xref py py-class docutils literal"><span class="pre">StringField</span></tt>, containing the form input
value. This is only when there is a single value corresponding to
the input name. <tt class="xref py py-class docutils literal"><span class="pre">StringField</span></tt> is a subclass of
<tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> which provides the additional
<tt class="xref py py-attr docutils literal"><span class="pre">StringField.value</span></tt> attribute for compatibility with
standard library <tt class="xref py py-mod docutils literal"><span class="pre">cgi</span></tt> module.</li>
<li>An instance of a <a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> class, if the input is a file
upload.</li>
<li>A list of <tt class="xref py py-class docutils literal"><span class="pre">StringField</span></tt> and/or <a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a>
objects. This is when multiple values exist, such as for a
<tt class="docutils literal"><span class="pre">&lt;select&gt;</span></tt> HTML form element.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unlike the standard library <tt class="xref py py-mod docutils literal"><span class="pre">cgi</span></tt> module
<a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> class, a <a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> object is returned
<em>only</em> when it is a file upload. In all other cases the return
is an instance of <tt class="xref py py-class docutils literal"><span class="pre">StringField</span></tt>. This means that you do
not need to use the <tt class="xref py py-attr docutils literal"><span class="pre">StringFile.value</span></tt> attribute to access
values of fields in most cases.</p>
</div>
<p>In addition to standard mapping object methods,
<a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> objects have the following attributes:</p>
<dl class="attribute">
<dt id="util.FieldStorage.list">
<tt class="descname">list</tt><a class="headerlink" href="#util.FieldStorage.list" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a list of <a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> objects, one for each
input. Multiple inputs with the same name will have multiple
elements in this list.</p>
</dd></dl>

</dd></dl>

<div class="section" id="fieldstorage-methods">
<span id="pyapi-util-fstor-meth"></span><h4><a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> methods<a class="headerlink" href="#fieldstorage-methods" title="Permalink to this headline">¶</a></h4>
<blockquote>
<div><dl class="method">
<dt id="util.add_field">
<tt class="descclassname">util.</tt><tt class="descname">add_field</tt><big>(</big><em>name</em>, <em>value</em><big>)</big><a class="headerlink" href="#util.add_field" title="Permalink to this definition">¶</a></dt>
<dd><p>Adds an additional form field with <em>name</em> and <em>value</em>.  If a
form field already exists with <em>name</em>, the <em>value</em> will be added
to the list of existing values for the form field.  This method
should be used for adding additional fields in preference to
adding new fields direct to the list of fields.</p>
<p>If the value associated with a field should be replaced when it
already exists, rather than an additional value being associated
with the field, the dictionary like subscript operator should be
used to set the value, or the existing field deleted altogether
first using the <tt class="docutils literal"><span class="pre">del</span></tt> operator.</p>
</dd></dl>

<dl class="method">
<dt id="util.clear">
<tt class="descclassname">util.</tt><tt class="descname">clear</tt><big>(</big><big>)</big><a class="headerlink" href="#util.clear" title="Permalink to this definition">¶</a></dt>
<dd><p>Removes all form fields. Individual form fields can be deleted
using the <tt class="docutils literal"><span class="pre">del</span></tt> operator.</p>
</dd></dl>

<dl class="method">
<dt id="util.get">
<tt class="descclassname">util.</tt><tt class="descname">get</tt><big>(</big><em>name</em>, <em>default</em><big>)</big><a class="headerlink" href="#util.get" title="Permalink to this definition">¶</a></dt>
<dd><p>If there is only one value associated with form field <em>name</em>,
that single value will be returned. If there are multiple values,
a list is returned holding all values. If no such form field or
value exists then the method returns the value specified by the
parameter <em>default</em>.  A subscript operator is also available
which yields the same result except that an exception will be
raised where the form field <em>name</em> does not exist.</p>
</dd></dl>

<dl class="method">
<dt id="util.getfirst">
<tt class="descclassname">util.</tt><tt class="descname">getfirst</tt><big>(</big><em>name</em><span class="optional">[</span>, <em>default</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#util.getfirst" title="Permalink to this definition">¶</a></dt>
<dd><p>Always returns only one value associated with form field
<em>name</em>. If no such form field or value exists then the method
returns the value specified by the optional parameter
<em>default</em>. This parameter defaults to <tt class="xref docutils literal"><span class="pre">None</span></tt> if not specified.</p>
</dd></dl>

<dl class="method">
<dt id="util.getlist">
<tt class="descclassname">util.</tt><tt class="descname">getlist</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#util.getlist" title="Permalink to this definition">¶</a></dt>
<dd><p>This method always returns a list of values associated with form
field <em>name</em>. The method returns an empty list if no such form
field or value exists for <em>name</em>. It returns a list consisting
of one item if only one such value exists.</p>
</dd></dl>

<dl class="method">
<dt id="util.has_key">
<tt class="descclassname">util.</tt><tt class="descname">has_key</tt><big>(</big><em>name</em><big>)</big><a class="headerlink" href="#util.has_key" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns <tt class="xref docutils literal"><span class="pre">True</span></tt> if <em>name</em> is a valid form field. The <tt class="docutils literal"><span class="pre">in</span></tt>
operator is also supported and will call this method.</p>
</dd></dl>

<dl class="method">
<dt id="util.items">
<tt class="descclassname">util.</tt><tt class="descname">items</tt><big>(</big><big>)</big><a class="headerlink" href="#util.items" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a list consisting of tuples for each combination of form
field name and value.</p>
</dd></dl>

<dl class="method">
<dt id="util.keys">
<tt class="descclassname">util.</tt><tt class="descname">keys</tt><big>(</big><big>)</big><a class="headerlink" href="#util.keys" title="Permalink to this definition">¶</a></dt>
<dd><p>This method returns the names of the form fields. The <tt class="docutils literal"><span class="pre">len</span></tt>
operator is also supported and will return the number of names
which would be returned by this method.</p>
</dd></dl>

</div></blockquote>
</div>
</div>
<div class="section" id="fieldstorage-examples">
<span id="pyapi-util-fstor-examples"></span><h3>FieldStorage Examples<a class="headerlink" href="#fieldstorage-examples" title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><p>The following examples demonstrate how to use the <em>file_callback</em>
parameter of the <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> constructor to control file
object creation. The <tt class="xref py py-class docutils literal"><span class="pre">Storage</span></tt> classes created in both
examples derive from FileType, thereby providing extended file
functionality.</p>
<p>These examples are provided for demonstration purposes only. The
issue of temporary file location and security must be considered
when providing such overrides with mod_python in production use.</p>
</div></blockquote>
<div class="section" id="simple-file-control-using-class-constructor">
<h4>Simple file control using class constructor<a class="headerlink" href="#simple-file-control-using-class-constructor" title="Permalink to this headline">¶</a></h4>
<blockquote>
<div><p>This example uses the <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> class constructor to
create the file object, allowing simple control. It is not
advisable to add class variables to this if serving multiple
sites from apache. In that case use the factory method instead:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Storage</span><span class="p">(</span><span class="nb">file</span><span class="p">):</span>

   <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">advisory_filename</span><span class="p">):</span>
       <span class="bp">self</span><span class="o">.</span><span class="n">advisory_filename</span> <span class="o">=</span> <span class="n">advisory_filename</span>
       <span class="bp">self</span><span class="o">.</span><span class="n">delete_on_close</span> <span class="o">=</span> <span class="bp">True</span>
       <span class="bp">self</span><span class="o">.</span><span class="n">already_deleted</span> <span class="o">=</span> <span class="bp">False</span>
       <span class="bp">self</span><span class="o">.</span><span class="n">real_filename</span> <span class="o">=</span> <span class="s">&#39;/someTempDir/thingy-unique-thingy&#39;</span>
       <span class="nb">super</span><span class="p">(</span><span class="n">Storage</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">real_filename</span><span class="p">,</span> <span class="s">&#39;w+b&#39;</span><span class="p">)</span>

   <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
       <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">already_deleted</span><span class="p">:</span>
           <span class="k">return</span>
       <span class="nb">super</span><span class="p">(</span><span class="n">Storage</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
       <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">delete_on_close</span><span class="p">:</span>
           <span class="bp">self</span><span class="o">.</span><span class="n">already_deleted</span> <span class="o">=</span> <span class="bp">True</span>
           <span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">real_filename</span><span class="p">)</span>

   <span class="n">request_data</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">FieldStorage</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">keep_blank_values</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">file_callback</span><span class="o">=</span><span class="n">Storage</span><span class="p">)</span>
</pre></div>
</div>
</div></blockquote>
</div>
<div class="section" id="advanced-file-control-using-object-factory">
<h4>Advanced file control using object factory<a class="headerlink" href="#advanced-file-control-using-object-factory" title="Permalink to this headline">¶</a></h4>
<blockquote>
<div><p>Using a object factory can provide greater control over the
constructor parameters:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span>

<span class="k">class</span> <span class="nc">Storage</span><span class="p">(</span><span class="nb">file</span><span class="p">):</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">directory</span><span class="p">,</span> <span class="n">advisory_filename</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">advisory_filename</span> <span class="o">=</span> <span class="n">advisory_filename</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">delete_on_close</span> <span class="o">=</span> <span class="bp">True</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">already_deleted</span> <span class="o">=</span> <span class="bp">False</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">real_filename</span> <span class="o">=</span> <span class="n">directory</span> <span class="o">+</span> <span class="s">&#39;/thingy-unique-thingy&#39;</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">Storage</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">real_filename</span><span class="p">,</span> <span class="s">&#39;w+b&#39;</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">close</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">already_deleted</span><span class="p">:</span>
            <span class="k">return</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">Storage</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
        <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">delete_on_close</span><span class="p">:</span>
            <span class="bp">self</span><span class="o">.</span><span class="n">already_deleted</span> <span class="o">=</span> <span class="bp">True</span>
            <span class="n">os</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">real_filename</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">StorageFactory</span><span class="p">:</span>

    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">directory</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">dir</span> <span class="o">=</span> <span class="n">directory</span>

    <span class="k">def</span> <span class="nf">create</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">advisory_filename</span><span class="p">):</span>
        <span class="k">return</span> <span class="n">Storage</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">dir</span><span class="p">,</span> <span class="n">advisory_filename</span><span class="p">)</span>

<span class="n">file_factory</span> <span class="o">=</span> <span class="n">StorageFactory</span><span class="p">(</span><span class="n">someDirectory</span><span class="p">)</span>
<span class="c"># [...sometime later...]</span>
<span class="n">request_data</span> <span class="o">=</span> <span class="n">util</span><span class="o">.</span><span class="n">FieldStorage</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">keep_blank_values</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
                                 <span class="n">file_callback</span><span class="o">=</span><span class="n">file_factory</span><span class="o">.</span><span class="n">create</span><span class="p">)</span>
</pre></div>
</div>
</div></blockquote>
</div>
</div>
<div class="section" id="field-class">
<span id="pyapi-util-fstor-fld"></span><h3>Field class<a class="headerlink" href="#field-class" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="util.Field">
<em class="property">class </em><tt class="descclassname">util.</tt><tt class="descname">Field</tt><a class="headerlink" href="#util.Field" title="Permalink to this definition">¶</a></dt>
<dd><p>This class is used internally by <a class="reference internal" href="#util.FieldStorage" title="util.FieldStorage"><tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt></a> and is not
meant to be instantiated by the user. Each instance of a
<a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> class represents an HTML Form input.</p>
<p><a class="reference internal" href="#util.Field" title="util.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a> instances have the following attributes:</p>
<dl class="attribute">
<dt id="util.Field.name">
<tt class="descname">name</tt><a class="headerlink" href="#util.Field.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The input name.</p>
</dd></dl>

<dl class="attribute">
<dt id="util.Field.value">
<tt class="descname">value</tt><a class="headerlink" href="#util.Field.value" title="Permalink to this definition">¶</a></dt>
<dd><p>The input value. This attribute can be used to read data from a
file upload as well, but one has to exercise caution when
dealing with large files since when accessed via <a class="reference internal" href="#util.Field.value" title="util.Field.value"><tt class="xref py py-attr docutils literal"><span class="pre">value</span></tt></a>,
the whole file is read into memory.</p>
</dd></dl>

<dl class="attribute">
<dt id="util.Field.file">
<tt class="descname">file</tt><a class="headerlink" href="#util.Field.file" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a file-like object. For file uploads it points to a
<tt class="xref py py-class docutils literal"><span class="pre">TemporaryFile</span></tt> instance. (For more information see the
TemporaryFile class in the standard python <a class="reference external" href="http://docs.python.org/lib/module-tempfile.html">tempfile module</a>.</p>
<p>For simple values, it is a <tt class="xref py py-class docutils literal"><span class="pre">StringIO</span></tt> object, so you can read
simple string values via this attribute instead of using the <a class="reference internal" href="#util.Field.value" title="util.Field.value"><tt class="xref py py-attr docutils literal"><span class="pre">value</span></tt></a>
attribute as well.</p>
</dd></dl>

<dl class="attribute">
<dt id="util.Field.filename">
<tt class="descname">filename</tt><a class="headerlink" href="#util.Field.filename" title="Permalink to this definition">¶</a></dt>
<dd><p>The name of the file as provided by the client.</p>
</dd></dl>

<dl class="attribute">
<dt id="util.Field.type">
<tt class="descname">type</tt><a class="headerlink" href="#util.Field.type" title="Permalink to this definition">¶</a></dt>
<dd><p>The content-type for this input as provided by the client.</p>
</dd></dl>

<dl class="attribute">
<dt id="util.Field.type_options">
<tt class="descname">type_options</tt><a class="headerlink" href="#util.Field.type_options" title="Permalink to this definition">¶</a></dt>
<dd><p>This is what follows the actual content type in the <tt class="docutils literal"><span class="pre">content-type</span></tt>
header provided by the client, if anything. This is a dictionary.</p>
</dd></dl>

<dl class="attribute">
<dt id="util.Field.disposition">
<tt class="descname">disposition</tt><a class="headerlink" href="#util.Field.disposition" title="Permalink to this definition">¶</a></dt>
<dd><p>The value of the first part of the <tt class="docutils literal"><span class="pre">content-disposition</span></tt> header.</p>
</dd></dl>

<dl class="attribute">
<dt id="util.Field.disposition_options">
<tt class="descname">disposition_options</tt><a class="headerlink" href="#util.Field.disposition_options" title="Permalink to this definition">¶</a></dt>
<dd><p>The second part (if any) of the <tt class="docutils literal"><span class="pre">content-disposition</span></tt> header in
the form of a dictionary.</p>
</dd></dl>

<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><span class="target" id="index-25"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc1867.html"><strong>RFC 1867</strong></a></dt>
<dd>Form-based File Upload in HTML for a description of form-based file uploads</dd>
</dl>
</div>
</dd></dl>

</div>
<div class="section" id="other-functions">
<span id="pyapi-util-funcs"></span><h3>Other functions<a class="headerlink" href="#other-functions" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="util.parse_qs">
<tt class="descclassname">util.</tt><tt class="descname">parse_qs</tt><big>(</big><em>qs</em><span class="optional">[</span>, <em>keep_blank_values</em><span class="optional">[</span>, <em>strict_parsing</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#util.parse_qs" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is functionally equivalent to the standard library
<tt class="xref py py-func docutils literal"><span class="pre">cgi.parse_qs()</span></tt>, except that it is written in C and is
much faster.</p>
<blockquote>
<div><p>Parse a query string given as a string argument (data of type
<tt class="docutils literal"><span class="pre">application/x-www-form-urlencoded</span></tt>).  Data are returned as a
dictionary.  The dictionary keys are the unique query variable
names and the values are lists of values for each name.</p>
<p>The optional argument <em>keep_blank_values</em> is a flag indicating
whether blank values in URL encoded queries should be treated as
blank strings.  A true value indicates that blanks should be
retained as blank strings.  The default false value indicates that
blank values are to be ignored and treated as if they were not
included.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <em>strict_parsing</em> argument is not yet implemented.</p>
</div>
</div></blockquote>
</dd></dl>

<dl class="function">
<dt id="util.parse_qsl">
<tt class="descclassname">util.</tt><tt class="descname">parse_qsl</tt><big>(</big><em>qs</em><span class="optional">[</span>, <em>keep_blank_values</em><span class="optional">[</span>, <em>strict_parsing</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#util.parse_qsl" title="Permalink to this definition">¶</a></dt>
<dd><p>This function is functionally equivalent to the standard library
<tt class="xref py py-func docutils literal"><span class="pre">cgi.parse_qsl()</span></tt>, except that it is written in C and is much
faster.</p>
<blockquote>
<div><p>Parse a query string given as a string argument (data of type
<tt class="docutils literal"><span class="pre">application/x-www-form-urlencoded</span></tt>).  Data are returned as a
list of name, value pairs.</p>
<p>The optional argument <em>keep_blank_values</em> is a flag indicating
whether blank values in URL encoded queries should be treated as
blank strings.  A true value indicates that blanks should be
retained as blank strings.  The default false value indicates that
blank values are to be ignored and treated as if they were not
included.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <em>strict_parsing</em> argument is not yet implemented.</p>
</div>
</div></blockquote>
</dd></dl>

<dl class="function">
<dt id="util.redirect">
<tt class="descclassname">util.</tt><tt class="descname">redirect</tt><big>(</big><em>req</em>, <em>location</em><span class="optional">[</span>, <em>permanent=0</em><span class="optional">[</span>, <em>text=None</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#util.redirect" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a convenience function to redirect the browser to another
location. When <em>permanent</em> is true, <tt class="xref py py-const docutils literal"><span class="pre">MOVED_PERMANENTLY</span></tt>
status is sent to the client, otherwise it is
<tt class="xref py py-const docutils literal"><span class="pre">MOVED_TEMPORARILY</span></tt>. A short text is sent to the browser
informing that the document has moved (for those rare browsers that
do not support redirection); this text can be overridden by
supplying a <em>text</em> string.</p>
<blockquote>
<div><p>If this function is called after the headers have already been sent,
an <tt class="xref py py-exc docutils literal"><span class="pre">IOError</span></tt> is raised.</p>
<p>This function raises <tt class="xref py py-exc docutils literal"><span class="pre">apache.SERVER_RETURN</span></tt> exception with a
value of <tt class="xref py py-const docutils literal"><span class="pre">apache.DONE</span></tt> to ensuring that any later phases or
stacked handlers do not run. If you do not want this, you can wrap
the call to <a class="reference internal" href="#util.redirect" title="util.redirect"><tt class="xref py py-func docutils literal"><span class="pre">redirect()</span></tt></a> in a try/except block catching the
<tt class="xref py py-exc docutils literal"><span class="pre">apache.SERVER_RETURN</span></tt>.</p>
</div></blockquote>
</dd></dl>

</div>
</div>
<div class="section" id="module-Cookie">
<span id="cookie-http-state-management"></span><span id="pyapi-cookie"></span><h2><a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-mod docutils literal"><span class="pre">Cookie</span></tt></a> &#8211; HTTP State Management<a class="headerlink" href="#module-Cookie" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-mod docutils literal"><span class="pre">Cookie</span></tt></a> module provides convenient ways for creating,
parsing, sending and receiving HTTP Cookies, as defined in the
specification published by Netscape.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Even though there are official IETF RFC&#8217;s describing HTTP State
Management Mechanism using cookies, the de facto standard supported
by most browsers is the original Netscape specification.
Furthermore, true compliance with IETF standards is actually
incompatible with many popular browsers, even those that claim to
be RFC-compliant. Therefore, this module supports the current
common practice, and is not fully RFC compliant.</p>
<p class="last">More specifically, the biggest difference between Netscape and RFC
cookies is that RFC cookies are sent from the browser to the server
along with their attributes (like Path or Domain). The
<a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-mod docutils literal"><span class="pre">Cookie</span></tt></a> module ignore those incoming attributes, so all
incoming cookies end up as Netscape-style cookies, without any of
their attributes defined.</p>
</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="http://web.archive.org/web/20070202195439/http://wp.netscape.com/newsref/std/cookie_spec.html">Persistent Client State - HTTP Cookies</a></dt>
<dd>for the original Netscape specification.</dd>
<dt><span class="target" id="index-26"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc2109.html"><strong>RFC 2109</strong></a></dt>
<dd>HTTP State Management Mechanism for the first RFC on Cookies.</dd>
<dt><span class="target" id="index-27"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc2694.html"><strong>RFC 2694</strong></a></dt>
<dd>Use of HTTP State Management for guidelines on using Cookies.</dd>
<dt><span class="target" id="index-28"></span><a class="rfc reference external" href="http://tools.ietf.org/html/rfc2965.html"><strong>RFC 2965</strong></a></dt>
<dd>HTTP State Management Mechanism for the latest IETF standard.</dd>
<dt><a class="reference external" href="http://arxiv.org/abs/cs.SE/0105018">HTTP Cookies: Standards, Privacy, and Politics</a></dt>
<dd>by David M. Kristol for an excellent overview of the issues surrounding standardization of Cookies.</dd>
</dl>
</div>
<div class="section" id="classes">
<span id="pyapi-cookie-classes"></span><h3>Classes<a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="Cookie.Cookie">
<em class="property">class </em><tt class="descclassname">Cookie.</tt><tt class="descname">Cookie</tt><big>(</big><em>name</em>, <em>value</em><span class="optional">[</span>, <em>attributes</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cookie.Cookie" title="Permalink to this definition">¶</a></dt>
<dd><p>This class is used to construct a single cookie named <em>name</em> and
having <em>value</em> as the value. Additionally, any of the attributes
defined in the Netscape specification and RFC2109 can by supplied
as keyword arguments.</p>
<p>The attributes of the class represent cookie attributes, and their
string representations become part of the string representation of
the cookie. The <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> class restricts attribute names to
only valid values, specifically, only the following attributes are
allowed: <tt class="docutils literal"><span class="pre">name,</span> <span class="pre">value,</span> <span class="pre">version,</span> <span class="pre">path,</span> <span class="pre">domain,</span> <span class="pre">secure,</span> <span class="pre">comment,</span> <span class="pre">expires,</span> <span class="pre">max_age,</span> <span class="pre">commentURL,</span> <span class="pre">discard,</span> <span class="pre">port,</span> <span class="pre">httponly,</span> <span class="pre">__data__</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">__data__</span></tt> attribute is a general-purpose dictionary that can
be used for storing arbitrary values, when necessary (This is
useful when subclassing <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a>).</p>
<p>The <tt class="xref py py-attr docutils literal"><span class="pre">expires</span></tt> attribute is a property whose value is checked
upon setting to be in format <tt class="docutils literal"><span class="pre">'Wdy,</span> <span class="pre">DD-Mon-YYYY</span> <span class="pre">HH:MM:SS</span> <span class="pre">GMT'</span></tt>
(as dictated per Netscape cookie specification), or a numeric value
representing time in seconds since beginning of epoch (which will
be automatically correctly converted to GMT time string). An
invalid <tt class="docutils literal"><span class="pre">expires</span></tt> value will raise <tt class="xref py py-exc docutils literal"><span class="pre">ValueError</span></tt>.</p>
<p>When converted to a string, a <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> will be in correct
format usable as value in a <tt class="docutils literal"><span class="pre">'Cookie'</span></tt> or <tt class="docutils literal"><span class="pre">'Set-Cookie'</span></tt>
header.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unlike the Python Standard Library Cookie classes, this class
represents a single cookie (referred to as <em class="dfn">Morsel</em> in
Python Standard Library).</p>
</div>
<dl class="method">
<dt id="Cookie.Cookie.parse">
<tt class="descname">parse</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#Cookie.Cookie.parse" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a class method that can be used to create a
<a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> instance from a cookie string <em>string</em> as
passed in a header value. During parsing, attribute names are
converted to lower case.</p>
<p>Because this is a class method, it must be called explicitly
specifying the class.</p>
<p>This method returns a dictionary of <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> instances,
not a single <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> instance.</p>
<p>Here is an example of getting a single <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> instance:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">mycookies</span> <span class="o">=</span> <span class="n">Cookie</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s">&quot;spam=eggs; expires=Sat, 14-Jun-2003 02:42:36 GMT&quot;</span><span class="p">)</span>
<span class="n">spamcookie</span> <span class="o">=</span> <span class="n">mycookies</span><span class="p">[</span><span class="s">&quot;spam&quot;</span><span class="p">]</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Because this method uses a dictionary, it is not possible to
have duplicate cookies. If you would like to have more than
one value in a single cookie, consider using a
<a class="reference internal" href="#Cookie.MarshalCookie" title="Cookie.MarshalCookie"><tt class="xref py py-class docutils literal"><span class="pre">MarshalCookie</span></tt></a>.</p>
</div>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="Cookie.SignedCookie">
<em class="property">class </em><tt class="descclassname">Cookie.</tt><tt class="descname">SignedCookie</tt><big>(</big><em>name</em>, <em>value</em>, <em>secret</em><span class="optional">[</span>, <em>attributes</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cookie.SignedCookie" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a subclass of <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a>. This class creates cookies
whose name and value are automatically signed using HMAC (md5) with
a provided secret <em>secret</em>, which must be a non-empty string.</p>
<dl class="method">
<dt id="Cookie.SignedCookie.parse">
<tt class="descname">parse</tt><big>(</big><em>string</em>, <em>secret</em><big>)</big><a class="headerlink" href="#Cookie.SignedCookie.parse" title="Permalink to this definition">¶</a></dt>
<dd><p>This method acts the same way as <a class="reference internal" href="#Cookie.Cookie.parse" title="Cookie.Cookie.parse"><tt class="xref py py-class docutils literal"><span class="pre">Cookie.parse()</span></tt></a>, but
also verifies that the cookie is correctly signed. If the
signature cannot be verified, the object returned will be of
class <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a>:</p>
<div class="highlight-python"><pre>..  note::</pre>
</div>
<blockquote>
<div><p>Always check the types of objects returned by
:meth:SignedCookie.parse(). If it is an instance of
<a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> (as opposed to <a class="reference internal" href="#Cookie.SignedCookie" title="Cookie.SignedCookie"><tt class="xref py py-class docutils literal"><span class="pre">SignedCookie</span></tt></a>), the
signature verification has failed:</p>
<div class="highlight-python"><pre># assume spam is supposed to be a signed cookie
if type(spam) is not Cookie.SignedCookie:
   # do something that indicates cookie isn't signed correctly</pre>
</div>
</div></blockquote>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="Cookie.MarshalCookie">
<em class="property">class </em><tt class="descclassname">Cookie.</tt><tt class="descname">MarshalCookie</tt><big>(</big><em>name</em>, <em>value</em>, <em>secret</em><span class="optional">[</span>, <em>attributes</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cookie.MarshalCookie" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a subclass of <a class="reference internal" href="#Cookie.SignedCookie" title="Cookie.SignedCookie"><tt class="xref py py-class docutils literal"><span class="pre">SignedCookie</span></tt></a>. It allows for <em>value</em>
to be any marshallable objects. Core Python types such as string,
integer, list, etc. are all marshallable object. For a complete
list see <a class="reference external" href="http://www.python.org/doc/current/lib/module-marshal.html">marchal</a>
module documentation.</p>
<p>When parsing, the signature is checked first, so incorrectly signed
cookies will not be unmarshalled.</p>
</dd></dl>

<div class="section" id="pyapi-cookie-func">
<span id="id1"></span><h4>Functions<a class="headerlink" href="#pyapi-cookie-func" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="Cookie.add_cookie">
<tt class="descclassname">Cookie.</tt><tt class="descname">add_cookie</tt><big>(</big><em>req</em>, <em>cookie</em><span class="optional">[</span>, <em>value</em>, <em>attributes</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cookie.add_cookie" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a convenience function for setting a cookie in request
headers. <em>req</em> is a mod_python <tt class="xref py py-class docutils literal"><span class="pre">Request</span></tt> object.  If
<em>cookie</em> is an instance of <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> (or subclass thereof),
then the cookie is set, otherwise, <em>cookie</em> must be a string, in
which case a <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> is constructed using <em>cookie</em> as
name, <em>value</em> as the value, along with any valid <a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a>
attributes specified as keyword arguments.</p>
<p>This function will also set <tt class="docutils literal"><span class="pre">'Cache-Control:</span> <span class="pre">no-cache=&quot;set-cookie&quot;'</span></tt>
header to inform caches that the cookie value should not be cached.</p>
<p>Here is one way to use this function:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">c</span> <span class="o">=</span> <span class="n">Cookie</span><span class="o">.</span><span class="n">Cookie</span><span class="p">(</span><span class="s">&#39;spam&#39;</span><span class="p">,</span> <span class="s">&#39;eggs&#39;</span><span class="p">,</span> <span class="n">expires</span><span class="o">=</span><span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span><span class="o">+</span><span class="mi">300</span><span class="p">)</span>
<span class="n">Cookie</span><span class="o">.</span><span class="n">add_cookie</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">c</span><span class="p">)</span>
</pre></div>
</div>
<p>Here is another:</p>
<blockquote>
<div>Cookie.add_cookie(req, &#8216;spam&#8217;, &#8216;eggs&#8217;, expires=time.time()+300)</div></blockquote>
</dd></dl>

<dl class="function">
<dt id="Cookie.get_cookies">
<tt class="descclassname">Cookie.</tt><tt class="descname">get_cookies</tt><big>(</big><em>req</em><span class="optional">[</span>, <em>Class</em><span class="optional">[</span>, <em>data</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cookie.get_cookies" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a convenience function for retrieving cookies from incoming
headers. <em>req</em> is a mod_python <tt class="xref py py-class docutils literal"><span class="pre">Request</span></tt> object. <em>Class</em>
is a class whose <tt class="xref py py-meth docutils literal"><span class="pre">parse()</span></tt> method will be used to parse the
cookies, it defaults to <tt class="docutils literal"><span class="pre">Cookie</span></tt>. <em>data</em> can be any number of
keyword arguments which, will be passed to <tt class="xref py py-meth docutils literal"><span class="pre">parse()</span></tt> (This
is useful for <tt class="xref py py-class docutils literal"><span class="pre">signedCookie</span></tt> and <a class="reference internal" href="#Cookie.MarshalCookie" title="Cookie.MarshalCookie"><tt class="xref py py-class docutils literal"><span class="pre">MarshalCookie</span></tt></a>
which require <tt class="docutils literal"><span class="pre">secret</span></tt> as an additional argument to
<tt class="xref py py-meth docutils literal"><span class="pre">parse()</span></tt>). The set of cookies found is returned as a
dictionary.</p>
</dd></dl>

<dl class="function">
<dt id="Cookie.get_cookie">
<tt class="descclassname">Cookie.</tt><tt class="descname">get_cookie</tt><big>(</big><em>req</em>, <em>name</em><span class="optional">[</span>, <em>Class</em><span class="optional">[</span>, <em>data</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#Cookie.get_cookie" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a convenience function for retrieving a single named cookie
from incoming headers. <em>req</em> is a mod_python <tt class="xref py py-class docutils literal"><span class="pre">Request</span></tt>
object. <em>name</em> is the name of the cookie. <em>Class</em> is a class
whose <tt class="xref py py-meth docutils literal"><span class="pre">parse()</span></tt> method will be used to parse the cookies, it
defaults to <tt class="docutils literal"><span class="pre">Cookie</span></tt>. <em>Data</em> can be any number of keyword
arguments which, will be passed to <tt class="xref py py-meth docutils literal"><span class="pre">parse()</span></tt> (This is useful
for <tt class="xref py py-class docutils literal"><span class="pre">signedCookie</span></tt> and <a class="reference internal" href="#Cookie.MarshalCookie" title="Cookie.MarshalCookie"><tt class="xref py py-class docutils literal"><span class="pre">MarshalCookie</span></tt></a> which require
<tt class="docutils literal"><span class="pre">secret</span></tt> as an additional argument to <tt class="xref py py-meth docutils literal"><span class="pre">parse()</span></tt>). The cookie
if found is returned, otherwise <tt class="xref docutils literal"><span class="pre">None</span></tt> is returned.</p>
</dd></dl>

</div>
</div>
<div class="section" id="examples">
<span id="pyapi-cookie-example"></span><h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
<p>This example sets a simple cookie which expires in 300 seconds:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">Cookie</span><span class="p">,</span> <span class="n">apache</span>
<span class="kn">import</span> <span class="nn">time</span>

<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>

    <span class="n">cookie</span> <span class="o">=</span> <span class="n">Cookie</span><span class="o">.</span><span class="n">Cookie</span><span class="p">(</span><span class="s">&#39;eggs&#39;</span><span class="p">,</span> <span class="s">&#39;spam&#39;</span><span class="p">)</span>
    <span class="n">cookie</span><span class="o">.</span><span class="n">expires</span> <span class="o">=</span> <span class="n">time</span><span class="o">.</span><span class="n">time</span><span class="p">()</span> <span class="o">+</span> <span class="mi">300</span>
    <span class="n">Cookie</span><span class="o">.</span><span class="n">add_cookie</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">cookie</span><span class="p">)</span>

    <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;This response contains a cookie!</span><span class="se">\n</span><span class="s">&#39;</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
<p>This example checks for incoming marshal cookie and displays it to the
client. If no incoming cookie is present a new marshal cookie is set.
This example uses <tt class="docutils literal"><span class="pre">'secret007'</span></tt> as the secret for HMAC signature:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span><span class="p">,</span> <span class="n">Cookie</span>

<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>

    <span class="n">cookies</span> <span class="o">=</span> <span class="n">Cookie</span><span class="o">.</span><span class="n">get_cookies</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">Cookie</span><span class="o">.</span><span class="n">MarshalCookie</span><span class="p">,</span>
                                    <span class="n">secret</span><span class="o">=</span><span class="s">&#39;secret007&#39;</span><span class="p">)</span>
    <span class="k">if</span> <span class="n">cookies</span><span class="o">.</span><span class="n">has_key</span><span class="p">(</span><span class="s">&#39;spam&#39;</span><span class="p">):</span>
        <span class="n">spamcookie</span> <span class="o">=</span> <span class="n">cookies</span><span class="p">[</span><span class="s">&#39;spam&#39;</span><span class="p">]</span>

        <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;Great, a spam cookie was found: </span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span> \
                                      <span class="o">%</span> <span class="nb">str</span><span class="p">(</span><span class="n">spamcookie</span><span class="p">))</span>
        <span class="k">if</span> <span class="nb">type</span><span class="p">(</span><span class="n">spamcookie</span><span class="p">)</span> <span class="ow">is</span> <span class="n">Cookie</span><span class="o">.</span><span class="n">MarshalCookie</span><span class="p">:</span>
            <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;Here is what it looks like decoded: </span><span class="si">%s</span><span class="s">=</span><span class="si">%s</span><span class="se">\n</span><span class="s">&#39;</span>
                      <span class="o">%</span> <span class="p">(</span><span class="n">spamcookie</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="n">spamcookie</span><span class="o">.</span><span class="n">value</span><span class="p">))</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;WARNING: The cookie found is not a </span><span class="se">\</span>
<span class="s">                       MarshalCookie, it may have been tapered with!&#39;</span><span class="p">)</span>

    <span class="k">else</span><span class="p">:</span>

        <span class="c"># MarshaCookie allows value to be any marshallable object</span>
        <span class="n">value</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;egg_count&#39;</span><span class="p">:</span> <span class="mi">32</span><span class="p">,</span> <span class="s">&#39;color&#39;</span><span class="p">:</span> <span class="s">&#39;white&#39;</span><span class="p">}</span>
        <span class="n">Cookie</span><span class="o">.</span><span class="n">add_cookie</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">Cookie</span><span class="o">.</span><span class="n">MarshalCookie</span><span class="p">(</span><span class="s">&#39;spam&#39;</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> \
                       <span class="s">&#39;secret007&#39;</span><span class="p">))</span>
        <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;Spam cookie not found, but we just set one!</span><span class="se">\n</span><span class="s">&#39;</span><span class="p">)</span>

    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="module-Session">
<span id="session-session-management"></span><span id="pyapi-sess"></span><h2><a class="reference internal" href="#module-Session" title="Session: Session Management"><tt class="xref py py-mod docutils literal"><span class="pre">Session</span></tt></a> &#8211; Session Management<a class="headerlink" href="#module-Session" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#module-Session" title="Session: Session Management"><tt class="xref py py-mod docutils literal"><span class="pre">Session</span></tt></a> module provides objects for maintaining persistent
sessions across requests.</p>
<p>The module contains a <a class="reference internal" href="#Session.BaseSession" title="Session.BaseSession"><tt class="xref py py-class docutils literal"><span class="pre">BaseSession</span></tt></a> class, which is not meant
to be used directly (it provides no means of storing a session),
<a class="reference internal" href="#Session.DbmSession" title="Session.DbmSession"><tt class="xref py py-class docutils literal"><span class="pre">DbmSession</span></tt></a> class, which uses a dbm to store sessions, and
<a class="reference internal" href="#Session.FileSession" title="Session.FileSession"><tt class="xref py py-class docutils literal"><span class="pre">FileSession</span></tt></a> class, which uses individual files to store
sessions.</p>
<p>The <a class="reference internal" href="#Session.BaseSession" title="Session.BaseSession"><tt class="xref py py-class docutils literal"><span class="pre">BaseSession</span></tt></a> class also provides session locking, both
across processes and threads. For locking it uses APR global_mutexes
(a number of them is pre-created at startup) The mutex number is
computed by using modulus of the session id <tt class="xref py py-func docutils literal"><span class="pre">hash()</span></tt>. (Therefore
it&#8217;s possible that different session id&#8217;s will have the same hash, but
the only implication is that those two sessions cannot be locked at
the same time resulting in a slight delay.)</p>
<div class="section" id="pyapi-sess-classes">
<span id="id2"></span><h3>Classes<a class="headerlink" href="#pyapi-sess-classes" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="Session.Session">
<tt class="descclassname">Session.</tt><tt class="descname">Session</tt><big>(</big><em>req</em><span class="optional">[</span>, <em>sid</em><span class="optional">[</span>, <em>secret</em><span class="optional">[</span>, <em>timeout</em><span class="optional">[</span>, <em>lock</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#Session.Session" title="Permalink to this definition">¶</a></dt>
<dd><p><a class="reference internal" href="#module-Session" title="Session: Session Management"><tt class="xref py py-func docutils literal"><span class="pre">Session()</span></tt></a> takes the same arguments as <a class="reference internal" href="#Session.BaseSession" title="Session.BaseSession"><tt class="xref py py-class docutils literal"><span class="pre">BaseSession</span></tt></a>.</p>
<p>This function returns a instance of the default session class. The
session class to be used can be specified using <tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.session.session_type</span> <span class="pre">value</span></tt>,
where <em>value</em> is one of
<a class="reference internal" href="#Session.DbmSession" title="Session.DbmSession"><tt class="xref py py-class docutils literal"><span class="pre">DbmSession</span></tt></a>, <a class="reference internal" href="#Session.MemorySession" title="Session.MemorySession"><tt class="xref py py-class docutils literal"><span class="pre">MemorySession</span></tt></a> or
<a class="reference internal" href="#Session.FileSession" title="Session.FileSession"><tt class="xref py py-class docutils literal"><span class="pre">FileSession</span></tt></a>.  Specifying custom session classes using
<tt class="docutils literal"><span class="pre">PythonOption</span></tt> session is not yet supported.</p>
<p>If session type option is not found, the function queries the MPM
and based on that returns either a new instance of
<a class="reference internal" href="#Session.DbmSession" title="Session.DbmSession"><tt class="xref py py-class docutils literal"><span class="pre">DbmSession</span></tt></a> or
<a class="reference internal" href="#Session.MemorySession" title="Session.MemorySession"><tt class="xref py py-class docutils literal"><span class="pre">MemorySession</span></tt></a>. <a class="reference internal" href="#Session.MemorySession" title="Session.MemorySession"><tt class="xref py py-class docutils literal"><span class="pre">MemorySession</span></tt></a> will be used if the
MPM is threaded and not forked (such is the case on Windows), or if
it threaded, forked, but only one process is allowed (the worker
MPM can be configured to run this way). In all other cases
<a class="reference internal" href="#Session.DbmSession" title="Session.DbmSession"><tt class="xref py py-class docutils literal"><span class="pre">DbmSession</span></tt></a> is used.</p>
<p>Note that on Windows if you are using multiple Python interpreter
instances and you need sessions to be shared between applications
running within the context of the distinct Python interpreter
instances, you must specifically indicate that <a class="reference internal" href="#Session.DbmSession" title="Session.DbmSession"><tt class="xref py py-class docutils literal"><span class="pre">DbmSession</span></tt></a>
should be used, as <a class="reference internal" href="#Session.MemorySession" title="Session.MemorySession"><tt class="xref py py-class docutils literal"><span class="pre">MemorySession</span></tt></a> will only allow a session
to be valid within the context of the same Python interpreter
instance.</p>
<p>Also note that the option name <tt class="docutils literal"><span class="pre">mod_python.session.session_type</span></tt>
only started to be used from mod_python 3.3 onwards. If you need to
retain compatibility with older versions of mod_python, you should
use the now obsolete <tt class="docutils literal"><span class="pre">session</span></tt> option instead.</p>
</dd></dl>

<dl class="class">
<dt id="Session.BaseSession">
<em class="property">class </em><tt class="descclassname">Session.</tt><tt class="descname">BaseSession</tt><big>(</big><em>req</em><span class="optional">[</span>, <em>sid</em><span class="optional">[</span>, <em>secret</em><span class="optional">[</span>, <em>timeout</em><span class="optional">[</span>, <em>lock</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#Session.BaseSession" title="Permalink to this definition">¶</a></dt>
<dd><p>This class is meant to be used as a base class for other classes
that implement a session storage mechanism. <em>req</em> is a required
reference to a mod_python request object.</p>
<p><a class="reference internal" href="#Session.BaseSession" title="Session.BaseSession"><tt class="xref py py-class docutils literal"><span class="pre">BaseSession</span></tt></a> is a subclass of <tt class="xref py py-class docutils literal"><span class="pre">dict</span></tt>. Data can be
stored and retrieved from the session by using it as a dictionary.</p>
<p><em>sid</em> is an optional session id; if provided, such a session must
already exist, otherwise it is ignored and a new session with a new
sid is created. If <em>sid</em> is not provided, the object will attempt
to look at cookies for session id. If a sid is found in cookies,
but it is not previously known or the session has expired, then a
new sid is created. Whether a session is &#8220;new&#8221; can be determined
by calling the <a class="reference internal" href="#Session.BaseSession.is_new" title="Session.BaseSession.is_new"><tt class="xref py py-meth docutils literal"><span class="pre">is_new()</span></tt></a> method.</p>
<p>Cookies generated by sessions will have a path attribute which is
calculated by comparing the server <tt class="docutils literal"><span class="pre">DocumentRoot</span></tt> and the
directory in which the <tt class="docutils literal"><span class="pre">PythonHandler</span></tt> directive currently in
effect was specified. E.g. if document root is <tt class="file docutils literal"><span class="pre">/a/b/c</span></tt> and
the directory <tt class="docutils literal"><span class="pre">PythonHandler</span></tt> was specified was <tt class="file docutils literal"><span class="pre">/a/b/c/d/e</span></tt>,
the path will be set to <tt class="file docutils literal"><span class="pre">/d/e</span></tt>.</p>
<p>The deduction of the path in this way will only work though where
the <tt class="docutils literal"><span class="pre">Directory</span></tt> directive is used and the directory is actually
within the document root. If the <tt class="docutils literal"><span class="pre">Location</span></tt> directive is used or
the directory is outside of the document root, the path will be set
to <tt class="file docutils literal"><span class="pre">/</span></tt>. You can force a specific path by setting the
<tt class="docutils literal"><span class="pre">mod_python.session.application_path</span></tt> option
(<tt class="docutils literal"><span class="pre">'PythonOption</span> <span class="pre">mod_python.session.application_path</span> <span class="pre">/my/path'</span></tt> in server
configuration).</p>
<p>Note that prior to mod_python 3.3, the option was
<tt class="docutils literal"><span class="pre">ApplicationPath</span></tt>.  If your system needs to be compatible with
older versions of mod_python, you should continue to use the now
obsolete option name.</p>
<p>The domain of a cookie is by default not set for a session and as
such the session is only valid for the host which generated it. In
order to have a session which spans across common sub domains, you
can specify the parent domain using the
<tt class="docutils literal"><span class="pre">mod_python.session.application_domain</span></tt> option
(<tt class="docutils literal"><span class="pre">'PythonOption</span> <span class="pre">mod_python.session.application_domain</span> <span class="pre">mod_python.org'</span></tt> in server
configuration).</p>
<p>When a <em>secret</em> is provided, <a class="reference internal" href="#Session.BaseSession" title="Session.BaseSession"><tt class="xref py py-class docutils literal"><span class="pre">BaseSession</span></tt></a> will use
<tt class="xref py py-class docutils literal"><span class="pre">SignedCookie</span></tt> when generating cookies thereby making the
session id almost impossible to fake. The default is to use plain
<a class="reference internal" href="#module-Cookie" title="Cookie: HTTP State Management"><tt class="xref py py-class docutils literal"><span class="pre">Cookie</span></tt></a> (though even if not signed, the session id is
generated to be very difficult to guess).</p>
<p>A session will timeout if it has not been accessed and a save
performed, within the <em>timeout</em> period. Upon a save occurring the
time of last access is updated and the period until the session
will timeout be reset.  The default <em>timeout</em> period is 30
minutes. An attempt to load an expired session will result in a
&#8220;new&#8221; session.</p>
<p>The <em>lock</em> argument (defaults to 1) indicates whether locking
should be used. When locking is on, only one session object with a
particular session id can be instantiated at a time.</p>
<p>A session is in &#8220;new&#8221; state when the session id was just generated,
as opposed to being passed in via cookies or the <em>sid</em> argument.</p>
<dl class="method">
<dt id="Session.BaseSession.is_new">
<tt class="descname">is_new</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.is_new" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns 1 if this session is new. A session will also be &#8220;new&#8221;
after an attempt to instantiate an expired or non-existent
session. It is important to use this method to test whether an
attempt to instantiate a session has succeeded, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sess</span> <span class="o">=</span> <span class="n">Session</span><span class="p">(</span><span class="n">req</span><span class="p">)</span>
<span class="k">if</span> <span class="n">sess</span><span class="o">.</span><span class="n">is_new</span><span class="p">():</span>
    <span class="c"># redirect to login</span>
    <span class="n">util</span><span class="o">.</span><span class="n">redirect</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="s">&#39;http://www.mysite.com/login&#39;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.id">
<tt class="descname">id</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.id" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the session id.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.created">
<tt class="descname">created</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.created" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the session creation time in seconds since beginning of
epoch.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.last_accessed">
<tt class="descname">last_accessed</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.last_accessed" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns last access time in seconds since beginning of epoch.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.timeout">
<tt class="descname">timeout</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns session timeout interval in seconds.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.set_timeout">
<tt class="descname">set_timeout</tt><big>(</big><em>secs</em><big>)</big><a class="headerlink" href="#Session.BaseSession.set_timeout" title="Permalink to this definition">¶</a></dt>
<dd><p>Set timeout to <em>secs</em>.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.invalidate">
<tt class="descname">invalidate</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.invalidate" title="Permalink to this definition">¶</a></dt>
<dd><p>This method will remove the session from the persistent store
and also place a header in outgoing headers to invalidate the
session id cookie.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.load">
<tt class="descname">load</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.load" title="Permalink to this definition">¶</a></dt>
<dd><p>Load the session values from storage.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.save">
<tt class="descname">save</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.save" title="Permalink to this definition">¶</a></dt>
<dd><p>This method writes session values to storage.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.delete">
<tt class="descname">delete</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.delete" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the session from storage.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.init_lock">
<tt class="descname">init_lock</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.init_lock" title="Permalink to this definition">¶</a></dt>
<dd><p>This method initializes the session lock. There is no need to
ever call this method, it is intended for subclasses that wish
to use an alternative locking mechanism.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.lock">
<tt class="descname">lock</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.lock" title="Permalink to this definition">¶</a></dt>
<dd><p>Locks this session. If the session is already locked by another
thread/process, wait until that lock is released. There is no
need to call this method if locking is handled automatically
(default).</p>
<p>This method registeres a cleanup which always unlocks the session
at the end of the request processing.</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.unlock">
<tt class="descname">unlock</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.unlock" title="Permalink to this definition">¶</a></dt>
<dd><p>Unlocks this session. (Same as <a class="reference internal" href="#Session.BaseSession.lock" title="Session.BaseSession.lock"><tt class="xref py py-meth docutils literal"><span class="pre">lock()</span></tt></a> - when locking is
handled automatically (default), there is no need to call this
method).</p>
</dd></dl>

<dl class="method">
<dt id="Session.BaseSession.cleanup">
<tt class="descname">cleanup</tt><big>(</big><big>)</big><a class="headerlink" href="#Session.BaseSession.cleanup" title="Permalink to this definition">¶</a></dt>
<dd><p>This method is for subclasses to implement session storage
cleaning mechanism (i.e. deleting expired sessions, etc.). It
will be called at random, the chance of it being called is
controlled by <tt class="xref py py-const docutils literal"><span class="pre">CLEANUP_CHANCE</span></tt> <a class="reference internal" href="#module-Session" title="Session: Session Management"><tt class="xref py py-mod docutils literal"><span class="pre">Session</span></tt></a> module
variable (default 1000). This means that cleanups will be
ordered at random and there is 1 in 1000 chance of it
happening. Subclasses implementing this method should not
perform the (potentially time consuming) cleanup operation in
this method, but should instead use
:meth:req.register_cleanup` to register a cleanup which will
be executed after the request has been processed.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="Session.DbmSession">
<em class="property">class </em><tt class="descclassname">Session.</tt><tt class="descname">DbmSession</tt><big>(</big><em>req</em><span class="optional">[</span>, <em>dbm</em><span class="optional">[</span>, <em>sid</em><span class="optional">[</span>, <em>secret</em><span class="optional">[</span>, <em>dbmtype</em><span class="optional">[</span>, <em>timeout</em><span class="optional">[</span>, <em>lock</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#Session.DbmSession" title="Permalink to this definition">¶</a></dt>
<dd><p>This class provides session storage using a dbm file. Generally,
dbm access is very fast, and most dbm implementations memory-map
files for faster access, which makes their performance nearly as
fast as direct shared memory access.</p>
<p><em>dbm</em> is the name of the dbm file (the file must be writable by the
httpd process). This file is not deleted when the server process is
stopped (a nice side benefit of this is that sessions can survive
server restarts). By default the session information is stored in a
dbmfile named <tt class="file docutils literal"><span class="pre">mp_sess.dbm</span></tt> and stored in a temporary
directory returned by <tt class="docutils literal"><span class="pre">tempfile.gettempdir()</span></tt> standard library
function. An alternative directory can be specified using
<tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.dbm_session.database_directory</span> <span class="pre">/path/to/directory</span></tt>.
The path and filename can can be overridden by
setting <tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.dbm_session.database_filename</span> <span class="pre">filename</span></tt>.</p>
<p>Note that the above names for the <tt class="docutils literal"><span class="pre">PythonOption</span></tt> settings were
changed to these values in mod_python 3.3. If you need to retain
compatibility with older versions of mod_python, you should
continue to use the now obsolete <tt class="docutils literal"><span class="pre">session_directory</span></tt> and
<tt class="docutils literal"><span class="pre">session_dbm</span></tt> options.</p>
<p>The implementation uses Python <tt class="xref py py-mod docutils literal"><span class="pre">anydbm</span></tt> module, which will
default to <tt class="xref py py-mod docutils literal"><span class="pre">dbhash</span></tt> on most systems. If you need to use a
specific dbm implementation (e.g. <tt class="xref py py-mod docutils literal"><span class="pre">gdbm</span></tt>), you can pass that
module as <em>dbmtype</em>.</p>
<p>Note that using this class directly is not cross-platform. For best
compatibility across platforms, always use the <a class="reference internal" href="#module-Session" title="Session: Session Management"><tt class="xref py py-func docutils literal"><span class="pre">Session()</span></tt></a>
function to create sessions.</p>
</dd></dl>

<dl class="class">
<dt id="Session.FileSession">
<em class="property">class </em><tt class="descclassname">Session.</tt><tt class="descname">FileSession</tt><big>(</big><em>req</em><span class="optional">[</span>, <em>sid</em><span class="optional">[</span>, <em>secret</em><span class="optional">[</span>, <em>timeout</em><span class="optional">[</span>, <em>lock</em><span class="optional">[</span>, <em>fast_cleanup</em><span class="optional">[</span>, <em>verify_cleanup</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#Session.FileSession" title="Permalink to this definition">¶</a></dt>
<dd><p>New in version 3.2.0.</p>
<p>This class provides session storage using a separate file for each
session. It is a subclass of <tt class="xref py py-mod docutils literal"><span class="pre">BaseSession</span></tt>.</p>
<p>Session data is stored in a separate file for each session. These
files are not deleted when the server process is stopped, so
sessions are persistent across server restarts.  The session files
are saved in a directory named mp_sess in the temporary directory
returned by the <tt class="docutils literal"><span class="pre">tempfile.gettempdir()</span></tt> standard library
function. An alternate path can be set using
<tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.file_session.database_directory</span> <span class="pre">/path/to/directory</span></tt>.
This directory must exist and be readable and writeable by the apache process.</p>
<p>Note that the above name for the <tt class="docutils literal"><span class="pre">PythonOption</span></tt> setting was
changed to these values in mod_python 3.3. If you need to retain
compatibility with older versions of mod_python, you should
continue to use the now obsolete <tt class="docutils literal"><span class="pre">session_directory</span></tt> option.</p>
<p>Expired session files are periodically removed by the cleanup mechanism.
The behaviour of the cleanup can be controlled using the
<em>fast_cleanup</em> and <em>verify_cleanup</em> parameters, as well as
<tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.file_session.cleanup_time_limit</span></tt> and
<tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.file_session.cleanup_grace_period</span></tt>.</p>
<ul>
<li><p class="first"><em>fast_cleanup</em></p>
<blockquote>
<div><p>A boolean value used to turn on FileSession cleanup
optimization.  Default is <em>True</em> and will result in reduced
cleanup time when there are a large number of session files.</p>
<p>When <em>fast_cleanup</em> is True, the modification time for the
session file is used to determine if it is a candidate for
deletion.  If <tt class="docutils literal"><span class="pre">(current_time</span> <span class="pre">-</span> <span class="pre">file_modification_time)</span> <span class="pre">&gt;</span> <span class="pre">(timeout</span> <span class="pre">+</span> <span class="pre">grace_period)</span></tt>,
the file will be a candidate for
deletion. If <em>verify_cleanup</em> is False, no futher checks will be
made and the file will be deleted.</p>
</div></blockquote>
<p>If <em>fast_cleanup</em> is False, the session file will unpickled and
it&#8217;s timeout value used to determine if the session is a
candidate for deletion. <em>fast_cleanup</em> = <tt class="xref docutils literal"><span class="pre">False</span></tt> implies
<em>verify_cleanup</em> = <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p>The timeout used in the fast_cleanup calculation is same as the
timeout for the session in the current request running the
filesession_cleanup. If your session objects are not using the
same timeout, or you are manually setting the timeout for a
particular session with <tt class="docutils literal"><span class="pre">set_timeout()</span></tt>, you will need to set
<em>verify_cleanup</em> = <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p>The value of <em>fast_cleanup</em> can also be set using
<tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.file_session.enable_fast_cleanup</span></tt>.</p>
</li>
<li><p class="first"><em>verify_cleanup</em></p>
<blockquote>
<div><p>Boolean value used to optimize the FileSession cleanup process.
Default is <tt class="xref docutils literal"><span class="pre">True</span></tt>.</p>
<p>If <em>verify_cleanup</em> is True, the session file which is being
considered for deletion will be unpickled and its timeout value
will be used to decide if the file should be deleted.</p>
<p>When <em>verify_cleanup</em> is False, the timeout value for the
current session will be used in to determine if the session has
expired. In this case, the session data will not be read from
disk, which can lead to a substantial performance improvement
when there are a large number of session files, or where each
session is saving a large amount of data. However this may
result in valid sessions being deleted if all the sessions are
not using a the same timeout value.</p>
<p>The value of <em>verify_cleanup</em> can also be set using
<tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.file_session.verify_session_timeout</span></tt>.</p>
</div></blockquote>
</li>
<li><dl class="first docutils">
<dt><tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.file_session.cleanup_time_limit</span> <span class="pre">[value]</span></tt></dt>
<dd><p class="first last">Integer value in seconds. Default is 2 seconds.</p>
</dd>
</dl>
<p>Session cleanup could potentially take a long time and be both
cpu and disk intensive, depending on the number of session files
and if each file needs to be read to verify the timeout value. To
avoid overloading the server, each time filesession_cleanup is
called it will run for a maximum of <em>session_cleanup_time_limit</em>
seconds.  Each cleanup call will resume from where the previous
call left off so all session files will eventually be checked.</p>
<p>Setting <em>session_cleanup_time_limit</em> to 0 will disable this
feature and filesession_cleanup will run to completion each time
it is called.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">mod_python.file_session.cleanup_grace_period</span> <span class="pre">[value]</span></tt>
Integer value in seconds. Default is 240 seconds. This value is added
to the session timeout in determining if a session file should be
deleted.</p>
<p>There is a small chance that a the cleanup for a given session
file may occur at the exact time that the session is being
accessed by another request. It is possible under certain
circumstances for that session file to be saved in the other
request only to be immediately deleted by the cleanup. To avoid
this race condition, a session is allowed a <em>grace_period</em> before
it is considered for deletion by the cleanup.  As long as the
grace_period is longer that the time it takes to complete the
request (which should normally be less than 1 second), the
session will not be mistakenly deleted by the cleanup.</p>
<p>The default value should be sufficient for most applications.</p>
</li>
</ul>
</dd></dl>

<dl class="class">
<dt id="Session.MemorySession">
<em class="property">class </em><tt class="descclassname">Session.</tt><tt class="descname">MemorySession</tt><big>(</big><em>req</em><span class="optional">[</span>, <em>sid</em><span class="optional">[</span>, <em>secret</em><span class="optional">[</span>, <em>timeout</em><span class="optional">[</span>, <em>lock</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#Session.MemorySession" title="Permalink to this definition">¶</a></dt>
<dd><p>This class provides session storage using a global dictionary. This
class provides by far the best performance, but cannot be used in a
multi-process configuration, and also consumes memory for every
active session. It also cannot be used where multiple Python
interpreters are used within the one Apache process and it is
necessary to share sessions between applications running in the
distinct interpreters.</p>
<p>Note that using this class directly is not cross-platform. For best
compatibility across platforms, always use the <a class="reference internal" href="#module-Session" title="Session: Session Management"><tt class="xref py py-func docutils literal"><span class="pre">Session()</span></tt></a>
function to create sessions.</p>
</dd></dl>

</div>
<div class="section" id="pyapi-sess-example">
<span id="id3"></span><h3>Examples<a class="headerlink" href="#pyapi-sess-example" title="Permalink to this headline">¶</a></h3>
<p>The following example demonstrates a simple hit counter.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">Session</span>

<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>
    <span class="n">session</span> <span class="o">=</span> <span class="n">Session</span><span class="o">.</span><span class="n">Session</span><span class="p">(</span><span class="n">req</span><span class="p">)</span>

    <span class="k">try</span><span class="p">:</span>
        <span class="n">session</span><span class="p">[</span><span class="s">&#39;hits&#39;</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">1</span>
    <span class="k">except</span><span class="p">:</span>
        <span class="n">session</span><span class="p">[</span><span class="s">&#39;hits&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>

    <span class="n">session</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>

    <span class="n">req</span><span class="o">.</span><span class="n">content_type</span> <span class="o">=</span> <span class="s">&#39;text/plain&#39;</span>
    <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&#39;Hits: </span><span class="si">%d</span><span class="se">\n</span><span class="s">&#39;</span> <span class="o">%</span> <span class="n">session</span><span class="p">[</span><span class="s">&#39;hits&#39;</span><span class="p">])</span>
    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="module-psp">
<span id="psp-python-server-pager"></span><span id="pyapi-psp"></span><h2><a class="reference internal" href="#module-psp" title="psp: Python Server Pages"><tt class="xref py py-mod docutils literal"><span class="pre">psp</span></tt></a> &#8211; Python Server Pager<a class="headerlink" href="#module-psp" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#module-psp" title="psp: Python Server Pages"><tt class="xref py py-mod docutils literal"><span class="pre">psp</span></tt></a> module provides a way to convert text documents
(including, but not limited to HTML documents) containing Python code
embedded in special brackets into pure Python code suitable for
execution within a mod_python handler, thereby providing a versatile
mechanism for delivering dynamic content in a style similar to ASP,
JSP and others.</p>
<p>The parser used by <a class="reference internal" href="#module-psp" title="psp: Python Server Pages"><tt class="xref py py-mod docutils literal"><span class="pre">psp</span></tt></a> is written in C (generated using flex)
and is therefore very fast.</p>
<p>See <a class="reference internal" href="handlers.html#hand-psp"><em>PSP Handler</em></a> for additional PSP information.</p>
<p>Inside the document, Python <em class="dfn">code</em> needs to be surrounded by
<tt class="docutils literal"><span class="pre">'&lt;%'</span></tt> and <tt class="docutils literal"><span class="pre">'%&gt;'</span></tt>. Python <em class="dfn">expressions</em> are enclosed in
<tt class="docutils literal"><span class="pre">'&lt;%='</span></tt> and <tt class="docutils literal"><span class="pre">'%&gt;'</span></tt>. A <em class="dfn">directive</em> can be enclosed in
<tt class="docutils literal"><span class="pre">'&lt;%&#64;'</span></tt> and <tt class="docutils literal"><span class="pre">'%&gt;'</span></tt>. A comment (which will never be part of
the resulting code) can be enclosed in <tt class="docutils literal"><span class="pre">'&lt;%--'</span></tt> and <tt class="docutils literal"><span class="pre">'--%&gt;'</span></tt></p>
<p>Here is a primitive PSP page that demonstrated use of both code and
expression embedded in an HTML document:</p>
<div class="highlight-python"><pre>&lt;html&gt;
&lt;%
import time
%&gt;
Hello world, the time is: &lt;%=time.strftime("%Y-%m-%d, %H:%M:%S")%&gt;
&lt;/html&gt;</pre>
</div>
<p>Internally, the PSP parser would translate the above page into the
following Python code:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&quot;&quot;&lt;html&gt;</span>
<span class="s">&quot;&quot;&quot;</span><span class="p">)</span>
<span class="kn">import</span> <span class="nn">time</span>
<span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&quot;&quot;</span>
<span class="s">Hello world, the time is: &quot;&quot;&quot;</span><span class="p">);</span> <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">time</span><span class="o">.</span><span class="n">strftime</span><span class="p">(</span><span class="s">&quot;%Y-%m-</span><span class="si">%d</span><span class="s">, %H:%M:%S&quot;</span><span class="p">)));</span> <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&quot;&quot;</span>
<span class="s">&lt;/html&gt;</span>
<span class="s">&quot;&quot;&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>This code, when executed inside a handler would result in a page
displaying words <tt class="docutils literal"><span class="pre">'Hello</span> <span class="pre">world,</span> <span class="pre">the</span> <span class="pre">time</span> <span class="pre">is:</span> <span class="pre">'</span></tt> followed by current time.</p>
<p>Python code can be used to output parts of the page conditionally or
in loops. Blocks are denoted from within Python code by
indentation. The last indentation in Python code (even if it is a
comment) will persist through the document until either end of
document or more Python code.</p>
<p>Here is an example:</p>
<div class="highlight-python"><pre>&lt;html&gt;
&lt;%
for n in range(3):
    # This indent will persist
%&gt;
&lt;p&gt;This paragraph will be
repeated 3 times.&lt;/p&gt;
&lt;%
# This line will cause the block to end
%&gt;
This line will only be shown once.&lt;br&gt;
&lt;/html&gt;</pre>
</div>
<p>The above will be internally translated to the following Python code:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&quot;&quot;&lt;html&gt;</span>
<span class="s">&quot;&quot;&quot;</span><span class="p">)</span>
<span class="k">for</span> <span class="n">n</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">3</span><span class="p">):</span>
    <span class="c"># This indent will persist</span>
    <span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&quot;&quot;</span>
<span class="s">&lt;p&gt;This paragraph will be</span>
<span class="s">repeated 3 times.&lt;/p&gt;</span>
<span class="s">&quot;&quot;&quot;</span><span class="p">)</span>
<span class="c"># This line will cause the block to end</span>
<span class="n">req</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s">&quot;&quot;&quot;</span>
<span class="s">This line will only be shown once.&lt;br&gt;</span>
<span class="s">&lt;/html&gt;</span>
<span class="s">&quot;&quot;&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The parser is also smart enough to figure out the indent if the last
line of Python ends with <tt class="docutils literal"><span class="pre">':'</span></tt> (colon). Considering this, and that the
indent is reset when a newline is encountered inside <tt class="docutils literal"><span class="pre">'&lt;%</span> <span class="pre">%&gt;'</span></tt>, the
above page can be written as:</p>
<div class="highlight-python"><pre>&lt;html&gt;
&lt;%
for n in range(3):
%&gt;
&lt;p&gt;This paragraph will be
repeated 3 times.&lt;/p&gt;
&lt;%
%&gt;
This line will only be shown once.&lt;br&gt;
&lt;/html&gt;</pre>
</div>
<p>However, the above code can be confusing, thus having descriptive
comments denoting blocks is highly recommended as a good practice.</p>
<p>The only directive supported at this time is <tt class="docutils literal"><span class="pre">include</span></tt>, here is
how it can be used:</p>
<div class="highlight-python"><pre>&lt;%@ include file="/file/to/include"%&gt;</pre>
</div>
<p>If the <a class="reference internal" href="#psp.parse" title="psp.parse"><tt class="xref py py-func docutils literal"><span class="pre">parse()</span></tt></a> function was called with the <em>dir</em> argument, then
the file can be specified as a relative path, otherwise it has to be
absolute:</p>
<div class="highlight-python"><pre>.. class:: PSP(req[, filename[, string[, vars]]])</pre>
</div>
<blockquote>
<div><p>This class represents a PSP object.</p>
<p><em>req</em> is a request object; <em>filename</em> and <em>string</em> are optional
keyword arguments which indicate the source of the PSP code. Only
one of these can be specified. If neither is specified,
<tt class="docutils literal"><span class="pre">req.filename</span></tt> is used as <em>filename</em>.</p>
<p><em>vars</em> is a dictionary of global variables. Vars passed in the
<tt class="xref py py-meth docutils literal"><span class="pre">run()</span></tt> method will override vars passed in here.</p>
<p>This class is used internally by the PSP handler, but can also be
used as a general purpose templating tool.</p>
<p>When a file is used as the source, the code object resulting from
the specified file is stored in a memory cache keyed on file name
and file modification time. The cache is global to the Python
interpreter. Therefore, unless the file modification time changes,
the file is parsed and resulting code is compiled only once per
interpreter.</p>
<p>The cache is limited to 512 pages, which depending on the size of
the pages could potentially occupy a significant amount of
memory. If memory is of concern, then you can switch to dbm file
caching. Our simple tests showed only 20% slower performance using
bsd db. You will need to check which implementation <tt class="xref py py-mod docutils literal"><span class="pre">anydbm</span></tt>
defaults to on your system as some dbm libraries impose a limit on
the size of the entry making them unsuitable. Dbm caching can be
enabled via <tt class="docutils literal"><span class="pre">mod_python.psp.cache_database_filename</span></tt> Python
option, e.g.:</p>
<div class="highlight-python"><pre>PythonOption mod_python.psp.cache_database_filename "/tmp/pspcache.dbm"</pre>
</div>
<p>Note that the dbm cache file is not deleted when the server
restarts.</p>
<p>Unlike with files, the code objects resulting from a string are
cached in memory only. There is no option to cache in a dbm file at
this time.</p>
<p>Note that the above name for the option setting was only changed to
this value in mod_python 3.3. If you need to retain backward
compatibility with older versions of mod_python use the
<tt class="docutils literal"><span class="pre">PSPDbmCache</span></tt> option instead.</p>
<dl class="method">
<dt id="psp.PSP.run">
<tt class="descclassname">PSP.</tt><tt class="descname">run</tt><big>(</big><span class="optional">[</span><em>vars</em><span class="optional">[</span>, <em>flush</em><span class="optional">]</span><span class="optional">]</span><big>)</big><a class="headerlink" href="#psp.PSP.run" title="Permalink to this definition">¶</a></dt>
<dd><p>This method will execute the code (produced at object
initialization time by parsing and compiling the PSP
source). Optional argument <em>vars</em> is a dictionary keyed by
strings that will be passed in as global variables. Optional
argument <em>flush</em> is a boolean flag indicating whether output
should be flushed. The default is not to flush output.</p>
<p>Additionally, the PSP code will be given global variables
<tt class="docutils literal"><span class="pre">req</span></tt>, <tt class="docutils literal"><span class="pre">psp</span></tt>, <tt class="docutils literal"><span class="pre">session</span></tt> and <tt class="docutils literal"><span class="pre">form</span></tt>. A session will be
created and assigned to <tt class="docutils literal"><span class="pre">session</span></tt> variable only if <tt class="docutils literal"><span class="pre">session</span></tt>
is referenced in the code (the PSP handler examines <tt class="docutils literal"><span class="pre">co_names</span></tt>
of the code object to make that determination). Remember that a
mere mention of <tt class="docutils literal"><span class="pre">session</span></tt> will generate cookies and turn on
session locking, which may or may not be what you
want. Similarly, a mod_python <tt class="xref py py-class docutils literal"><span class="pre">FieldStorage</span></tt> object will
be instantiated if <tt class="docutils literal"><span class="pre">form</span></tt> is referenced in the code.</p>
<p>The object passed in <tt class="docutils literal"><span class="pre">psp</span></tt> is an instance of
<a class="reference internal" href="#psp.PSPInterface" title="psp.PSPInterface"><tt class="xref py py-class docutils literal"><span class="pre">PSPInterface</span></tt></a>.</p>
</dd></dl>

<dl class="method">
<dt id="psp.PSP.display_code">
<tt class="descclassname">PSP.</tt><tt class="descname">display_code</tt><big>(</big><big>)</big><a class="headerlink" href="#psp.PSP.display_code" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an HTML-formatted string representing a side-by-side
listing of the original PSP code and resulting Python code
produced by the PSP parser.</p>
<p>Here is an example of how <tt class="xref py py-class docutils literal"><span class="pre">PSP</span></tt> can be used as a templating
mechanism:</p>
<p>The template file:</p>
<div class="highlight-python"><pre>&lt;html&gt;
  &lt;!-- This is a simple psp template called template.html --&gt;
  &lt;h1&gt;Hello, &lt;%=what%&gt;!&lt;/h1&gt;
&lt;/html&gt;</pre>
</div>
<p>The handler code:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">mod_python</span> <span class="kn">import</span> <span class="n">apache</span><span class="p">,</span> <span class="n">psp</span>

<span class="k">def</span> <span class="nf">handler</span><span class="p">(</span><span class="n">req</span><span class="p">):</span>
    <span class="n">template</span> <span class="o">=</span> <span class="n">psp</span><span class="o">.</span><span class="n">PSP</span><span class="p">(</span><span class="n">req</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s">&#39;template.html&#39;</span><span class="p">)</span>
    <span class="n">template</span><span class="o">.</span><span class="n">run</span><span class="p">({</span><span class="s">&#39;what&#39;</span><span class="p">:</span><span class="s">&#39;world&#39;</span><span class="p">})</span>
    <span class="k">return</span> <span class="n">apache</span><span class="o">.</span><span class="n">OK</span>
</pre></div>
</div>
</dd></dl>

</div></blockquote>
<dl class="class">
<dt id="psp.PSPInterface">
<em class="property">class </em><tt class="descclassname">psp.</tt><tt class="descname">PSPInterface</tt><a class="headerlink" href="#psp.PSPInterface" title="Permalink to this definition">¶</a></dt>
<dd><p>An object of this class is passed as a global variable <tt class="docutils literal"><span class="pre">psp</span></tt> to
the PSP code. Objects of this class are instantiated internally and
the interface to <tt class="xref py py-meth docutils literal"><span class="pre">__init__()</span></tt> is purposely undocumented.</p>
<dl class="method">
<dt id="psp.PSPInterface.set_error_page">
<tt class="descname">set_error_page</tt><big>(</big><em>filename</em><big>)</big><a class="headerlink" href="#psp.PSPInterface.set_error_page" title="Permalink to this definition">¶</a></dt>
<dd><p>Used to set a psp page to be processed when an exception
occurs. If the path is absolute, it will be appended to document
root, otherwise the file is assumed to exist in the same directory
as the current page. The error page will receive one additional
variable, <tt class="docutils literal"><span class="pre">exception</span></tt>, which is a 3-tuple returned by
<tt class="docutils literal"><span class="pre">sys.exc_info()</span></tt>.</p>
</dd></dl>

<dl class="method">
<dt id="psp.PSPInterface.apply_data">
<tt class="descname">apply_data</tt><big>(</big><em>object</em><span class="optional">[</span>, <em>**kw</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#psp.PSPInterface.apply_data" title="Permalink to this definition">¶</a></dt>
<dd><p>This method will call the callable object <em>object</em>, passing form
data as keyword arguments, and return the result.</p>
</dd></dl>

<dl class="method">
<dt id="psp.PSPInterface.redirect">
<tt class="descname">redirect</tt><big>(</big><em>location</em><span class="optional">[</span>, <em>permanent=0</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#psp.PSPInterface.redirect" title="Permalink to this definition">¶</a></dt>
<dd><p>This method will redirect the browser to location
<em>location</em>. If <em>permanent</em> is true, then
<tt class="xref py py-const docutils literal"><span class="pre">MOVED_PERMANENTLY</span></tt> will be sent (as opposed to
<tt class="xref py py-const docutils literal"><span class="pre">MOVED_TEMPORARILY</span></tt>).</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Redirection can only happen before any data is sent to the
client, therefore the Python code block calling this method must
be at the very beginning of the page. Otherwise an
<tt class="xref py py-exc docutils literal"><span class="pre">IOError</span></tt> exception will be raised.</p>
</div>
<p>Example:</p>
<div class="highlight-python"><pre>&lt;%

# note that the '&lt;' above is the first byte of the page!
psp.redirect('http://www.modpython.org')
%&gt;</pre>
</div>
</dd></dl>

</dd></dl>

<p>Additionally, the <a class="reference internal" href="#module-psp" title="psp: Python Server Pages"><tt class="xref py py-mod docutils literal"><span class="pre">psp</span></tt></a> module provides the following low level
functions:</p>
<dl class="function">
<dt id="psp.parse">
<tt class="descclassname">psp.</tt><tt class="descname">parse</tt><big>(</big><em>filename</em><span class="optional">[</span>, <em>dir</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#psp.parse" title="Permalink to this definition">¶</a></dt>
<dd><p>This function will open file named <em>filename</em>, read and parse its
content and return a string of resulting Python code.</p>
<p>If <em>dir</em> is specified, then the ultimate filename to be parsed is
constructed by concatenating <em>dir</em> and <em>filename</em>, and the argument
to <tt class="docutils literal"><span class="pre">include</span></tt> directive can be specified as a relative path. (Note
that this is a simple concatenation, no path separator will be
inserted if <em>dir</em> does not end with one).</p>
</dd></dl>

<dl class="function">
<dt id="psp.parsestring">
<tt class="descclassname">psp.</tt><tt class="descname">parsestring</tt><big>(</big><em>string</em><big>)</big><a class="headerlink" href="#psp.parsestring" title="Permalink to this definition">¶</a></dt>
<dd><p>This function will parse contents of <em>string</em> and return a string
of resulting Python code.</p>
</dd></dl>

</div>
<div class="section" id="module-httpdconf">
<span id="httpdconf-httpd-configuration"></span><span id="pyapi-httpdconf"></span><h2><a class="reference internal" href="#module-httpdconf" title="httpdconf: HTTPd Configuration"><tt class="xref py py-mod docutils literal"><span class="pre">httpdconf</span></tt></a> &#8211; HTTPd Configuration<a class="headerlink" href="#module-httpdconf" title="Permalink to this headline">¶</a></h2>
<p>The <a class="reference internal" href="#module-httpdconf" title="httpdconf: HTTPd Configuration"><tt class="xref py py-mod docutils literal"><span class="pre">httpdconf</span></tt></a> module provides a simple framework for generating
Apache HTTP Server configuration in Python. It was inspired by HTMLgen
by Robin Friedrich. <a class="reference internal" href="#module-httpdconf" title="httpdconf: HTTPd Configuration"><tt class="xref py py-mod docutils literal"><span class="pre">httpdconf</span></tt></a> appeared in 2002 as part of the
mod_python test framework and its use has been primarily limited to
mod_python tests. This latest version of mod_python includes many
improvements to <a class="reference internal" href="#module-httpdconf" title="httpdconf: HTTPd Configuration"><tt class="xref py py-mod docutils literal"><span class="pre">httpdconf</span></tt></a> and makes it part of the Python API.</p>
<p>The basic idea is that an Apache configuration directive can be
specified as Python code, e.g.:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">mod_python.httpdconf</span> <span class="kn">import</span> <span class="o">*</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">conf</span> <span class="o">=</span> <span class="n">DocumentRoot</span><span class="p">(</span><span class="s">&#39;/path/to/htdocs&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>The resulting object renders itself as a valid Apache directive when
converted to string:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">conf</span>
<span class="go">DocumentRoot /path/to/htdocs</span>
</pre></div>
</div>
<p>While the <tt class="docutils literal"><span class="pre">__repr__</span></tt> method of the object returns the string of
Python code used to construct it in the first place:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="sb">`conf`</span>
<span class="go">DocumentRoot(&#39;/path/to/htdocs&#39;)</span>
</pre></div>
</div>
<div class="section" id="classes-for-directive-types">
<h3>Classes for Directive types<a class="headerlink" href="#classes-for-directive-types" title="Permalink to this headline">¶</a></h3>
<p><a class="reference internal" href="#module-httpdconf" title="httpdconf: HTTPd Configuration"><tt class="xref py py-mod docutils literal"><span class="pre">httpdconf</span></tt></a> separates all Apache directives into the following
classes.</p>
<dl class="class">
<dt id="httpdconf.Directive">
<em class="property">class </em><tt class="descclassname">httpdconf.</tt><tt class="descname">Directive</tt><big>(</big><em>name</em>, <em>value</em><span class="optional">[</span>, <em>flipslash=1</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#httpdconf.Directive" title="Permalink to this definition">¶</a></dt>
<dd><p>This is a simple directive. Its syntax is the directive <em>name</em>
followed by a string <em>value</em>. Even though the Apache directives can
be followed by multiple arguments, <a class="reference internal" href="#module-httpdconf" title="httpdconf: HTTPd Configuration"><tt class="xref py py-mod docutils literal"><span class="pre">httpdconf</span></tt></a> views it as
just a single string, e.g. <tt class="docutils literal"><span class="pre">CustomLog('logs/access_log</span> <span class="pre">combined')</span></tt>.</p>
</dd></dl>

<dl class="class">
<dt id="httpdconf.Container">
<em class="property">class </em><tt class="descclassname">httpdconf.</tt><tt class="descname">Container</tt><big>(</big><em>*args</em><span class="optional">[</span>, <em>only_if=None</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#httpdconf.Container" title="Permalink to this definition">¶</a></dt>
<dd><p>A Container groups directives specified as <em>args</em> into a single
object. args can include other containers as well. The optional
<em>only_if</em> argument is a string of Python that is evaled at
directive render time. The directive is rendered only if the eval
return a true value.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Container</span><span class="p">(</span><span class="n">CustomLog</span><span class="p">(</span><span class="s">&#39;logs/access_log combined&#39;</span><span class="p">),</span> <span class="n">ErrorLog</span><span class="p">(</span><span class="s">&#39;logs/error_log&#39;</span><span class="p">))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">c</span>
<span class="go">CustomLog logs/access_log combined</span>
<span class="go">ErrorLog logs/error_log</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="sb">`c`</span>
<span class="go">Container(</span>
<span class="go">    CustomLog(&#39;logs/access_log combined&#39;),</span>
<span class="go">    ErrorLog(&#39;logs/error_log&#39;),</span>
<span class="go">    only_if=&#39;True&#39;)</span>
<span class="go">)</span>
</pre></div>
</div>
<p>Note how elements within a Container are properly indented when
rendered as Python code. A more practical example of only_if may be
<tt class="docutils literal"><span class="pre">only_if=&quot;mod_python.version.HTTPD_VERSION[0:3]</span> <span class="pre">==</span> <span class="pre">'2.4'&quot;</span></tt>.</p>
<dl class="method">
<dt id="httpdconf.Container.append">
<tt class="descname">append</tt><big>(</big><em>value</em><big>)</big><a class="headerlink" href="#httpdconf.Container.append" title="Permalink to this definition">¶</a></dt>
<dd><p>Appends an object to a container. There is no difference
between specifying contained object at creation time or
appending elements to a container later.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt>
<tt class="descname">ContainerTag(tag, attr, args[, flipslash=1)]</tt></dt>
<dd><p>A ContainerTag is a tag that contains other tags,
e.g. <tt class="docutils literal"><span class="pre">Directory</span></tt> or <tt class="docutils literal"><span class="pre">Location</span></tt>.</p>
</dd></dl>

<dl class="class">
<dt id="httpdconf.Comment">
<em class="property">class </em><tt class="descclassname">httpdconf.</tt><tt class="descname">Comment</tt><big>(</big><em>comment</em><big>)</big><a class="headerlink" href="#httpdconf.Comment" title="Permalink to this definition">¶</a></dt>
<dd><p>A Comment renders itself as an Apache configuration comment. There
is no need to include <tt class="docutils literal"><span class="pre">#</span></tt> as part of the <em>comment</em>
string. Multi-line comments can be specified by a newline
charater. Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Comment</span><span class="p">(</span><span class="s">&quot;</span><span class="se">\n</span><span class="s">This is</span><span class="se">\n</span><span class="s">a comment</span><span class="se">\n</span><span class="s">&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">c</span>
<span class="go">#</span>
<span class="go"># This is</span>
<span class="go"># a comment</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="sb">`c`</span>
<span class="go">Comment(&#39;\n&#39;</span>
<span class="go">        &#39;This is\n&#39;</span>
<span class="go">        &#39;a comment\n&#39;)</span>
</pre></div>
</div>
</dd></dl>

<p><a class="reference internal" href="#module-httpdconf" title="httpdconf: HTTPd Configuration"><tt class="xref py py-mod docutils literal"><span class="pre">httpdconf</span></tt></a> includes a basic set of Apache configuration
directives (see code for which ones), but any Apache configuration
directive can be trivially created by sub-classing one of the above
classes:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">mod_python.httpdconf</span> <span class="kn">import</span> <span class="o">*</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">MyDirective</span><span class="p">(</span><span class="n">Directive</span><span class="p">):</span>
<span class="gp">... </span>   <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">val</span><span class="p">):</span>
<span class="gp">... </span>      <span class="n">Directive</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">__class__</span><span class="o">.</span><span class="n">__name__</span><span class="p">,</span> <span class="n">val</span><span class="p">)</span>
<span class="gp">...</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">MyDirective</span><span class="p">(</span><span class="s">&#39;foo&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">print</span> <span class="n">c</span>
<span class="go">MyDirective foo</span>
</pre></div>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
  <h3><a href="contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Python API</a><ul>
<li><a class="reference internal" href="#multiple-interpreters">Multiple Interpreters</a></li>
<li><a class="reference internal" href="#overview-of-a-request-handler">Overview of a Request Handler</a></li>
<li><a class="reference internal" href="#overview-of-a-filter-handler">Overview of a Filter Handler</a></li>
<li><a class="reference internal" href="#overview-of-a-connection-handler">Overview of a Connection Handler</a></li>
<li><a class="reference internal" href="#module-apache"><tt class="docutils literal"><span class="pre">apache</span></tt> &#8211; Access to Apache Internals.</a><ul>
<li><a class="reference internal" href="#functions">Functions</a></li>
<li><a class="reference internal" href="#attributes">Attributes</a></li>
<li><a class="reference internal" href="#table-object-mp-table">Table Object (mp_table)</a></li>
<li><a class="reference internal" href="#request-object">Request Object</a><ul>
<li><a class="reference internal" href="#request-methods">Request Methods</a></li>
<li><a class="reference internal" href="#request-members">Request Members</a></li>
</ul>
</li>
<li><a class="reference internal" href="#connection-object-mp-conn">Connection Object (mp_conn)</a><ul>
<li><a class="reference internal" href="#connection-methods">Connection Methods</a></li>
<li><a class="reference internal" href="#connection-members">Connection Members</a></li>
</ul>
</li>
<li><a class="reference internal" href="#filter-object-mp-filter">Filter Object (mp_filter)</a><ul>
<li><a class="reference internal" href="#filter-methods">Filter Methods</a></li>
<li><a class="reference internal" href="#filter-members">Filter Members</a></li>
<li><a class="reference internal" href="#server-object-mp-server">Server Object (mp_server)</a></li>
<li><a class="reference internal" href="#server-methods">Server Methods</a></li>
<li><a class="reference internal" href="#server-members">Server Members</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#module-util"><tt class="docutils literal"><span class="pre">util</span></tt> &#8211; Miscellaneous Utilities</a><ul>
<li><a class="reference internal" href="#fieldstorage-class">FieldStorage class</a><ul>
<li><a class="reference internal" href="#fieldstorage-methods"><tt class="docutils literal"><span class="pre">FieldStorage</span></tt> methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#fieldstorage-examples">FieldStorage Examples</a><ul>
<li><a class="reference internal" href="#simple-file-control-using-class-constructor">Simple file control using class constructor</a></li>
<li><a class="reference internal" href="#advanced-file-control-using-object-factory">Advanced file control using object factory</a></li>
</ul>
</li>
<li><a class="reference internal" href="#field-class">Field class</a></li>
<li><a class="reference internal" href="#other-functions">Other functions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-Cookie"><tt class="docutils literal"><span class="pre">Cookie</span></tt> &#8211; HTTP State Management</a><ul>
<li><a class="reference internal" href="#classes">Classes</a><ul>
<li><a class="reference internal" href="#pyapi-cookie-func">Functions</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examples">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-Session"><tt class="docutils literal"><span class="pre">Session</span></tt> &#8211; Session Management</a><ul>
<li><a class="reference internal" href="#pyapi-sess-classes">Classes</a></li>
<li><a class="reference internal" href="#pyapi-sess-example">Examples</a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-psp"><tt class="docutils literal"><span class="pre">psp</span></tt> &#8211; Python Server Pager</a></li>
<li><a class="reference internal" href="#module-httpdconf"><tt class="docutils literal"><span class="pre">httpdconf</span></tt> &#8211; HTTPd Configuration</a><ul>
<li><a class="reference internal" href="#classes-for-directive-types">Classes for Directive types</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="tutorial.html"
                        title="previous chapter">Tutorial</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="directives.html"
                        title="next chapter">Apache Configuration Directives</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/pythonapi.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="directives.html" title="Apache Configuration Directives"
             >next</a> |</li>
        <li class="right" >
          <a href="tutorial.html" title="Tutorial"
             >previous</a> |</li>
        <li><a href="contents.html">Mod_python v3.4.1-3.4.1 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
        &copy; <a href="copyright.html">Copyright</a> 1990-2013, Apache Software Foundation, Gregory Trubetskoy.
      Last updated on Oct 22, 2013.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
    </div>
  </body>
</html>